Software Vault: The Gold Collection

home *** CD-ROM | disk | FTP | other *** search

/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr12 / pplasc.zip / PPL2.ASC < prev next >

Wrap

Text File | 1993-06-04 | 246KB | 6,744 lines

PPL Reference Lists by Type PPL is composed of basically five different token types. They are constants, functions, statements, types, and variables. Constant List AUTO BELL DEFS ECHODOTS ERASELINE FALSE FCL FIELDLEN FNS F_EXP F_MW F_REG F_SEL F_SYS GRAPH GUIDE HIGHASCII LANG LFAFTER LFBEFORE LOGIT LOGITLEFT NC NEWLINE NOCLEAR O_RD O_RW O_WR SEC STACKED S_DB S_DN S_DR S_DW TRUE UPCASE WORDWRAP YESNO Function List ABORT ABS AND ANSION ASC B2W CALLID CALLNUM CARRIER CCTYPE CDON CHR CURCOLOR CURCONF CURSEC DATE DAY DBGLEVEL DEFCOLOR DOW EXIST FERR FILEINF FMTCC GETENV GETTOKEN GETX GETY GRAFMODE HELPPATH HOUR I2S INKEY INSTR KINKEY LANGEXT LEFT LEN LOGGEDON LOWER LTRIM MASK_ALNUM MASK_ALPHA MASK_ASCII MASK_FILE MASK_NUM MASK_PATH MASK_PWD MAXNODE MGETBYTE MID MIN MINKEY MINLEFT MINON MKADDR MKDATE MODEM MONTH NOCHAR NOT ONLOCAL OR PAGESTAT PCBDAT PCBNODE PEEKB PEEKDW PEEKW PPENAME PPEPATH PSA RANDOM READLINE REGAH REGAL REGAX REGBH REGBL REGBX REGCF REGCH REGCL REGCX REGDH REGDI REGDL REGDS REGDX REGES REGF REGSI REPLACE RIGHT RTRIM S2I SCRTEXT SEC SHOWSTAT SLPATH SPACE STRING STRIP STRIPATX SYSOPSEC TEMPPATH TIME TIMEAP TOKCOUNT TOKENSTR TRIM UPPER UN_CITY UN_NAME UN_OPER UN_STAT U_BDL U_BDLDAY U_BUL U_FDL U_FUL U_INCONF U_LDATE U_LDIR U_LOGONS U_LTIME U_MSGRD U_MSGWR U_NAME U_PWDHIST U_PWDLC U_PWDTC U_RECNUM U_STAT U_TIMEON VALCC VALDATE VALTIME VER XOR YEAR YESCHAR Statement List ADJTIME ANSIPOS BACKUP BLT BROADCAST BYE CALL CDCHKOFF CDCHKON CHAT CLOSECAP CLREOL CLS COLOR CONFFLAG CONFUNFLAG DBGLEVEL DEC DEFCOLOR DELAY DELETE DELUSER DIR DISPFILE DISPSTR DISPTEXT DOINTR DTROFF DTRON ELSE ELSEIF END ENDIF ENDWHILE FAPPEND FCLOSE FCREATE FGET FOPEN FOR FORWARD FPUT FPUTLN FPUTPAD FRESHLINE FREWIND GETTOKEN GETUSER GOODBYE GOSUB GOTO HANGUP IF INC INPUT INPUTCC INPUTDATE INPUTINT INPUTMONEY INPUTSTR INPUTTEXT INPUTTIME INPUTYN JOIN KBDCHKOFF KBDCHKON KBDFILE KBDSTUFF LET LOG MESSAGE MORE MPRINT MPRINTLN NEWLINE NEWLINES NEWPWD NEXT OPENCAP OPTEXT PAGEOFF PAGEON POKEB POKEDW POKEW POP PRINT PRINTLN PROMPTSTR PUSH PUTUSER QUEST RDUNET RDUSYS RENAME RESETDISP RESTSCRN RETURN SAVESCRN SENDMODEM SHELL SHOWOFF SHOWON SOUND SPRINT SPRINTLN STARTDISP STOP TOKENIZE VARADDR VAROFF VARSEG WAIT WAITFOR WHILE WRUNET WRUSYS Type List BOOLEAN DATE INTEGER MONEY STRING TIME Variable List U_CLS U_DEF79 U_EXPERT U_FSE U_FSEP U_LONGHDR U_SCROLL U_EXPDATE U_PWDEXP U_EXPSEC U_PAGELEN U_SEC U_ADDR(5) U_ALIAS U_BDPHONE U_CITY U_CMNT1 U_CMNT2 U_HVPHONE U_NOTES(4) U_PWD U_TRANS U_VER Lists by Category Unknown what lists will be necessary at this time. ??? List ??? ??? List ??? ABORT() Function Function Returns a flag indicating whether or not the user has aborted the display of information. Syntax ABORT() No arguments are required Return Type & Value BOOLEAN If the user has aborted the display of information by answering no to a MORE? prompt or by hitting ^K or ^X display, this function returns TRUE. Otherwise FALSE is returned. Remarks Unless specifically disabled, the user can abort any display at any time by hitting ^K or ^X or by answering no to a MORE? prompt. If the user does this, PCBoard will not display any further information until the display is reset via the RESETDISP statement. This function should be checked occasionally during long displays of information to determine if the user wants to abort. If the function returns TRUE, you should stop printing information and continue with the next part of the program after using RESETDISP. Examples INTEGER I STARTDISP FCL ' While the user has not aborted, continue WHILE (!ABORT()) DO PRINTLN "I is equal to ",I INC I ENDWHILE RESETDISP See Also RESETDISP Statement, STARTDISP Statement ABS() Function Function Returns the absolute value of an integer expression. Syntax ABS(iexp) iexp Any integer expression. Return Type & Value INTEGER If iexp is greater than or equal to 0, this function returns iexp. Otherwise this function returns -iexp. Remarks The most significant use of the absolute value function is to determine the difference between two values. For example, you may need to know in a program the difference between 8 and 13. Normal subtraction would yield a result of -5 (8-13). You don't need the mathematical difference though, you need the logical difference between the two integers. The absolute value function will return that. In other words, while 8-13 is -5, ABS(8-13) is 5, which may be a more desirable result in many cases. Also, it is easier to code and understand than this: INTEGER D LET D = 8-13 IF (D < 0) LET D = -D Examples INTEGER num ' Loop while num is < 6 or num > 10 ' ... ABS(4-8)=4 ABS( 5-8)=3 ABS( 6-8)=2 ABS( 7- 8)=1 ' ABS(9-8)=1 ABS(10-8)=2 ABS(11-8)=3 ABS(12- 8)=4 ... WHILE (ABS(num-8) > 2) DO PRINTLN "Enter a number from 6 to 10:" INPUT "Number",num ENDWHILE INTEGER i, r ' Generate 10 random numbers from -5 to 5 ' Print each number and it's absolute value FOR i = 1 TO 10 LET r = RANDOM(10)-5 PRINTLN "The absolute value of ",r," is ",ABS(r) NEXT See Also ADJTIME Statement Function Adjust the users time up or down. Syntax ADJTIME minutes minutes An integer expression containing the number of minutes that the users time left should be adjusted by. A value greater than 0 will add time; a value less than 0 will deduct time. Remarks Use this statement to reward (or penalize) the user with more (or less) time based on any condition or event you wish. However, the added/deducted time is only applied to the current call. It will not be remembered after the caller hangs up, except that it will be reflected in the time online today. For example, if a caller has a normal daily limit of 30 minutes and you add 15 minutes, they can stay online for up to 45 minutes. If they only stay online for 15 minutes and hangup, they will only have 15 minutes left at the beginning of the next call, not 30; the added time isn't saved. If they stay online for 40 minutes though, it will have given them their entire normal allotment of time plus 10 of the 15 extra minutes. If they try to call back to use their last 5 minutes they will not be able to because PCBoard will see that they've used their entire daily time limit plus 10 minutes. The last 5 minutes wasn't saved. Examples STRING yn INPUTYN "Do you wish to gamble 5 minutes for 10",yn,@X0E IF (yn = YESCHAR()) THEN IF (RANDOM(1) = 1) THEN PRINTLN "You *WON*! 10 extra minutes awarded . . ." ADJTIME 10 ELSE PRINTLN "You lost. Sorry, but I have to take 5 minutes now . . ." ADJTIME -5 ENDIF ELSE PRINTLN "Chicken! :)" ENDIF See Also AND() Function Function Calculate the bitwise AND of two integer arguments. Syntax AND(iexp1,iexp2) iexp1 Any integer expression. iexp2 Any integer expression. Return Type & Value INTEGER Returns the bitwise AND of iexp1 and iexp2. Remarks This function may be used to clear selected bits in an integer expression by ANDing the expression with a mask that has the bits to clear set to 0 and the bits to ignore set to 1. Another use is to calculate the remainder of a division operation by a power of two by ANDing the dividend with the power of two minus one. Examples ' Clear the high word, keeping only the low word PRINTLN "07FFFFFFFh AND 0FFFFh = ",AND(07FFFFFFFh,0FFFFh) ' In this case 123%16 = AND(123,15) (15 = 1111b) PRINTLN "The remainder of 123 divided by 16 is ",AND(123,1111b) See Also NOT() Function, OR() Function, XOR() Function ANSION() Function Function Report the status of ANSI availability with the current caller. Syntax ANSION() No arguments are required Return Type and Value BOOLEAN If the caller can support ANSI then TRUE is returned, otherwise FALSE is returned. Remarks This function will return TRUE if the caller has ANSI capabilities. This could have been determined one of two ways. If the user answered yes to the Do you want graphics? prompt this function will return TRUE. If the user answered no, there is still a chance that the user has ANSI capabilities; PCBoard will interrogate the remote computer to find out if ANSI is available. If it is, this function will return TRUE. Finally, if the user answered no and PCBoard was unable to detect ANSI at login this function will return FALSE. There is still a chance that the user could support ANSI but the only safe approach at this point is to assume that there is no ANSI available. Examples IF (ANSION()) PRINTLN "You have ANSI support available!" See Also ANSIPOS Statement, BACKUP Statement, FORWARD Statement, GETX() Function, GETY() Function, GRAFMODE() Function ANSIPOS Statement Function Position the cursor anywhere on the screen using an ANSI positioning escape sequence. Syntax ANSIPOS xpos, ypos xpos An integer expression with the screen column (x position) in which to place the cursor. Valid columns are 1 through 80. ypos An integer expression with the screen row (y position) on which to place the cursor. Valid rows are 1 through 23. Remarks This statement will position the cursor to the specified (X,Y) coordinate on the screen but only if the current caller has ANSI support. If you are writing a program that will require ANSI positioning, check the value of the ANSION() function. If ANSI is not available, this statement will be ignored. Examples CLS IF (ANSION()) THEN ANSIPOS 1,1 PRINTLN "This starts at (1,1)" ANSIPOS 3,3 PRINTLN "This starts at (3,3)" ANSIPOS 2,2 PRINTLN "And *THIS* starts at (2,2)" ENDIF See Also ANSION() Function, BACKUP Statement, FORWARD Statement, GETX() Function, GETY() Function, GRAFMODE() Function ASC() Function Function Converts a character to it's ASCII code. Syntax ASC(sexp) sexp Any string expression. Return Type & Value INTEGER Returns the ASCII code of the first character of sexp (1-255) or 0 if sexp is an empty string. Remarks In other languages (such as BASIC) you can have any of the 256 possible ASCII codes (0-255) in a string. In PPL you are limited to 255 codes (1-255) because ASCII 0 is used to terminate strings and can't appear in the middle of a string. So, if you ever get a 0 returned from this function, it is because you passed it an empty string. Examples PRINTLN "The ASCII code for S is ",ASC("S") ' Convert a lowercase s to uppercase STRING s LET s = CHR(ASC("s")-ASC("a")+ASC("A")) See Also CHR() Function AUTO Constant Function Set the auto answer flag in an INPUTSTR or PROMPTSTR statement. Value 8192 = 10000000000000b = 20000o = 2000h Remarks The INPUTSTR and PROMPTSTR statements have the ability to automatically answer themselves if left alone for 20 seconds. It can be especially useful if you are writing a program that should work with automated systems; use the AUTO constant and the question will automatically be answered after 20 seconds just in case the automation system doesn't know what to do with it. Examples STRING ans LET ans = NOCHAR() INPUTSTR "Run program now",ans,@X0E,1,"",AUTO+YESNO IF (ans = NOCHAR()) END See Also INPUTSTR Statement, PROMPTSTR Statement B2W() Function Function Convert two byte-sized arguments into a single word-sized argument. Syntax B2W(iexp1,iexp2) iexp1 Any integer expression with a value between 000h and 0FFh. iexp2 Any integer expression with a value between 000h and 0FFh. Return Type & Value INTEGER Returns a word-sized value between 00000h and 0FFFFh. The return value is computed by the following expression: iexp1+iexp2*0100h. Remarks It is sometimes necessary to combine two bytes together to form a word. This function simplifies that process, and speeds it up a little as well by doing it internally instead of requiring you to perform the arithmetic yourself. It can be especially useful when used with the DOINTR statement. Examples ' This line will display 25 *'s at the current screen position ' NOTES: 10h is the Video BIOS interrupt ' B2W(ASC("*"),09h) is the char to print and the service number ' 0007h is video page 0, attribute 7 ' 25 is the number of characters to print ' All others are 0 and not needed for this function DOINTR 10h,B2W(09h,ASC("*")),0007h,25,0,0,0,0,0,0 See Also DOINTR Statement BACKUP Statement Function Move the cursor backward a specified number of columns. Syntax BACKUP numcols numcols An integer expression of the number of columns to move backward. Valid values are 1 through 79. Remarks This statement will move the cursor backward, nondestructively, a specified number of columns. It will work with or without ANSI. If ANSI is available (as reported by the ANSION() function) then it will use an ANSI positioning command; otherwise it will use the specified number of backspace characters. ANSI is usually faster, but backspace characters will get the job done. Note that you cannot use this function to move beyond column 1; to do so would require ANSI. So, if the cursor is already in column 1 this statement will have no effect. And if the cursor is in column 80 the maximum you could move backward would be 79 (column 80 - 79 columns = column 1). Examples PRINT "Rolling dice -- " FOR i = 1 TO 10 LET d1 = RANDOM(5)+1 LET d2 = RANDOM(5)+1 PRINT d1,"-",d2 BACKUP 3 NEXT NEWLINE See Also ANSION() Function, ANSIPOS Statement, FORWARD Statement, GETX() Function, GETY() Function, GRAFMODE() Function BELL Constant Function Set the bell flag in a DISPTEXT statement. Value 2048 = 100000000000b = 4000o = 800h Remarks The DISPTEXT statement has the ability to sound a bell before displaying the actual text of a prompt. This is useful when you want to get the users attention when displaying information. It sends a ^G (ASCII 7) character to the remote caller and sounds the alarm on the local computer running PCBoard (unless the alarm has been toggled off). It is the responsibility of the users terminal software to support the ^G. Examples ' Get the users attention and display the closed board prompt DISPTEXT 11,BELL+LFAFTER+LFBEFORE See Also BLT Statement Function Display a specified bulletin number to the user. Syntax BLT bltnum bltnum The number of the bulletin to display to the user. Valid values are 1 through the number of bulletins available. Remarks This statement will display a specified bulletin number to the user. The BLT.LST file for the current conference will be searched for the bulletin. If the bulletin number is invalid (less than 1 or greater than the highest bulletin number defined) then nothing will be displayed. Examples INTEGER num INPUT "Bulletin to view",num BLT num See Also BOOLEAN Type Function Declare one or more variables of type boolean. Syntax BOOLEAN var|arr(s[,s[,s]])[,var|arr(s[,s[,s]])] var The name of a variable to declare. Must start with a letter [A-Z] which may be followed by letters, digits [0-9] or the underscore [_]. May be of any length but only the first 32 characters are used. arr The name of an array variable to declare. The same naming conventions as var are used. s The size (0-based) of an array variable dimension. Any constant integer expression is allowed. Remarks BOOLEAN variables can hold two values: 1 or 0 (TRUE or FALSE). It is stored internally as a one byte unsigned character. If a BOOLEAN is assigned to or from an INTEGER type then the value 1 or 0 is assigned. If a BOOLEAN is assigned to a STRING type then it is automatically converted to a string (either "1" or "0"). If a STRING is assigned to a BOOLEAN then the value of the string will be used; a 0 value will be taken as is, another other value will be converted to 1. All other types, when assigned to or from a BOOLEAN, will be converted to an INTEGER first before being assigned to or from the BOOLEAN type. Examples BOOLEAN flag, bit, isPrime(100), leapYears(2079- 1900) See Also DATE Type, INTEGER Type, MONEY Type, STRING Type, TIME Type BROADCAST Statement Function Broadcast a single line message to a range of nodes. Syntax BROADCAST lonode,hinode,message lonode An integer expression containing the low node number to which the message should be broadcast. hinode An integer expression containing the high node number to which the message should be broadcast. message A string expression containing the message text which should be broadcast to the specified nodes. Remarks This PPL statement functions the same as the PCBoard BROADCAST command, which is normally reserved for SysOp security level. This statement allows you to programatically broadcast a message to a range of nodes without giving users the ability to manually broadcast at any time they choose. Examples ' Broadcast a message to a specific node BROADCAST 5,5,"This broadcast from "+STRING(PCBNODE()) ' Broadcast to a range of nodes BROADCAST 4,8,"Stand-by for log off in 10 seconds" ' Broadcast to all nodes BROADCAST 1,65535,"Hello all!" See Also BYE Statement Function Log the user off as though they had typed the BYE command. Syntax BYE No arguments are required Remarks There are multiple ways for the user to log off. One is by typing G at the command prompt. That will warn them if they have files flagged for download and (optionally) confirm their selection (incase they accidentally hit G and ENTER). Another is the BYE command. PCBoard assumes that, if the user typed BYE instead of G, that they really want to log off, didn't type it in accidentally, and want to leave now. The BYE statement does just that. It is intended to provide you PPL with the same functionality as many PCBoard prompts where G or BYE can be entered at any point. Examples STRING s INPUT "What do you want to do",s IF (s = "G") THEN GOODBYE ELSEIF (s = "BYE") THEN BYE ELSE KBDSTUFF s ENDIF See Also GOODBYE Statement, HANGUP Statement CALL Statement Function Call (execute) another PPE file from the currently executing PPE. Syntax CALL filename filename A string expression containing the complete path and filename of a PPE file to load and execute. Remarks It is sometimes convienient to load and run complete programs from other programs, similar to how you process subroutines with GOSUB and RETURN. PPL supports running both external EXE and COM files via the SHELL statement and other PPE files via the CALL statement. CALL allows you to load and run another PPE file, after which control returns to the first PPE at the statement after the CALL. The second PPE is completely separate from the first. You may pass values to the PPE by tokenizing a string with the TOKENIZE statement. If you need to pass values back to the first PPE, you will need to create some sort of parameter passing convention yourself. For example, you may have the second PPE create a file that has the needed information for the first PPE. Examples STRING s INPUT "What PPE file do you wish to run",s CALL "C:\PCB\PPE\"+s+".PPE" See Also SHELL Statement CALLID() Function Function Access caller ID information returned from caller ID compatible modems. Syntax CALLID() No arguments are required Return Type & Value STRING Returns a string with caller ID information captured from a caller ID compatible modem. Remarks Some areas of the country have an optional service available which will send, to your modem (other other telephone device), the phone number and/or name of the person calling you. This service is known as 'Caller ID'. Some modems are starting to support it directly by capturing the information and sending it to you between the first and second rings. It can be very helpful in determining who is calling (or abusing) your BBS or for statistical purposes. This function will return the information if your modem supports it. Examples FAPPEND 1,"CID.LOG",O_WR,S_DW FPUTLN 1,LEFT(U_NAME(),30)+CALLID() FCLOSE 1 See Also CALLNUM() Function Function Returns the current caller number. Syntax CALLNUM() No arguments are required Return Type & Value INTEGER Returns the caller number of the user online. Remarks Everytime a user logs on to the system the system caller number is incremented. This function will return the caller number for use in your PPL applications. It is kept in the main conference MSGS file. Note that the number is not incremented until after the user has completely logged on to the system so you should generally wait until LOGGEDON() reports TRUE before using this function. Examples IF (LOGGEDON() & (CALLNUM() = 1000000)) THEN PRINTLN "@BEEP@CONGRATULATIONS!!!" PRINTLN "@BEEP@YOU ARE THE 1,000,000th CALLER!!!" PRINTLN "Upgrading security . . ." GETUSER LET U_SEC = 99 PUTUSER ENDIF See Also CARRIER() Function Function Determine what speed the current caller is connected at. Syntax CARRIER() No arguments are required Return Type & Value INTEGER Returns an integer with the connect speed of the current caller. Remarks Should the need arise for you to know what speed the caller is connected to the BBS at, this function will return that information. You should note that this information is not guaranteed accurate. It is the responsibility of the modem to tell PCBoard the actual connect speed, especially in locked port environments. For example, if your serial port is locked at 38400 bps, the modem can usually be configured to report either the actual connect speed (9600 bps, for example) or the locked port rate (38400 bps). PCBoard has to trust the modem; if the modem tells it 38400, it will have to live with that, as will your PPL applications. Examples IF (CARRIER() < 9600) THEN PRINTLN "Sorry, downloads are not permitted at speeds below 9600 bps" END ENDIF See Also CCTYPE() Function Function Determine what the type of a credit card is based on the credit card number. Syntax CCTYPE(ccnum) ccnum A string expression with the credit card number that is to be checked. Return Type & Value STRING Returns a string with the name of the card. Remarks PPL can be used to perform some simple credit card validation. This function returns the issuer of a credit card based on the credit card number. For example, a valid credit card number that starts with a "4" is a Visa card, so the string "VISA" will be returned. If a credit card is invalid (VALCC() = FALSE) or not recognized, then "UNKNOWN" will be returned. Other valid credit card with known types will return the appropriate string. The following card types are recognized by PPL: "DISCOVER", "CARTE BLANCHE", "DINERS CLUB", "OPTIMA", "AMERICAN EXPRESS", "VISA", and "MASTERCARD". Examples STRING s INPUT "Credit card number",s IF (VALCC(s)) PRINTLN LEFT(CCTYPE(s),20)," - ",FMTCC(s) See Also CDCHKOFF Statement Function Turn off carrier detect checking. Syntax CDCHKOFF No arguments are required Remarks PCBoard has built in automatic carrier detecting. What this means is that if someone should hangup unexpectedly, PCBoard will detect it, log it to the callers log, and recycle back to the call waiting screen. Some applications require the ability to turn this off; for example, a callback verification PPE needs to hangup on the caller and then do more processing. Normally, PCBoard would just recycle at that point. So, just before you start a section of code that should continue regardless of the existence of a caller online, you should issue a CDCHKOFF statement. It will turn off the automatic carrier checking. When you've finished the block where carrier checking has been disabled, issue the CDCHKON statement to turn it back on. Examples CDCHKOFF DTROFF DELAY 18 DTRON SENDMODEM "ATDT1800DATAFON" ' Please don't call this number! :) WAITFOR "CONNECT",60 CDCHKON See Also CDCHKON Statement CDCHKON Statement Function Turn on carrier detect checking. Syntax CDCHKON No arguments are required Remarks PCBoard has built in automatic carrier detecting. What this means is that if someone should hangup unexpectedly, PCBoard will detect it, log it to the callers log, and recycle back to the call waiting screen. Some applications require the ability to turn this off; for example, a callback verification PPE needs to hangup on the caller and then do more processing. Normally, PCBoard would just recycle at that point. So, just before you start a section of code that should continue regardless of the existence of a caller online, you should issue a CDCHKOFF statement. It will turn off the automatic carrier checking. When you've finished the block where carrier checking has been disabled, issue the CDCHKON statement to turn it back on. Examples CDCHKOFF DTROFF DELAY 18 DTRON SENDMODEM "ATDT1800DATAFON" ' Please don't call this number! :) WAITFOR "CONNECT",60 CDCHKON See Also CDCHKOFF Statement CDON() Function Function Determine if carrier detect in on or not. Syntax CDON() No arguments are required Return Type & Value BOOLEAN Returns a boolean TRUE if carrier detect is on, FALSE otherwise. Remarks If you have used CDCHKOFF to turn off automatic carrier detect checking PCBoard will not automatically detect and act on a carrier loss. If necessary, this function can be used to detect a carrier loss condition and act appropriately. Examples IF (!CDON()) THEN LOG "Carrier lost in PPE "+PPENAME(),FALSE HANGUP ENDIF See Also CHAT Statement Function Enter SysOp chat mode. Syntax CHAT No arguments are required Remarks One of the features of PCBoard where change is often requested is the operator page facility. Some people want to be able to configure multiple ranges of availability per day, some want a different sounding page bell, longer or shorter page attempts, etc, etc. This statement, along with the PAGEON and PAGEOFF statements and the PAGESTAT() function, allow you to implement an operator page in any way desired. Of course, the SysOp may still start a chat with the F10 key or by responding to the default O (operator page) command, and the CHAT statement may be used at anytime (although you'll generally want to avoid starting it unless you've confirmed that the SysOp is available since the user has no way to exit it himself). Examples PAGEON FOR i = 1 TO 10 PRINT "@BEEP@" DELAY 18 IF (KINKEY() = " ") THEN CHAT GOTO exit ENDIF NEXT :exit See Also PAGEOFF Statement, PAGEOFF Statement, PAGESTAT() Function CHR() Function Function Converts an ASCII code to a character. Syntax CHR(iexp) iexp Any integer expression between 0 and 255. Return Type & Value STRING Returns a one character long string for ASCII codes from 1 to 255 or an empty string for ASCII code 0. Remarks In other languages (such as BASIC) you can have any of the 256 possible ASCII codes (0-255) in a string. In PPL you are limited to 255 codes (1-255) because ASCII 0 is used to terminate strings and can't appear in the middle of a string. So, if you ever get an empty string from this function, it is because you passed it a 0. Any other value will return a valid string with a single character. Examples PRINTLN "The ASCII code for S is ",ASC("S") ' Convert a lowercase s to uppercase STRING s LET s = CHR(ASC("s")-ASC("a")+ASC("A")) See Also ASC() Function CLOSECAP Statement Function Close the screen capture file. Syntax CLOSECAP No arguments are required Remarks PCBoard has the ability to capture screen output to a file for later reference. PPL allows that same ability via the OPENCAP and CLOSECAP statements. This could be useful in a program that executes a series of commands in non-stop mode. The process could open a capture file first, execute the commands, close the capture file, then allow the user to view or download the capture file. CLOSECAP closes the capture file and turns off screen capturing. Also, the SHOWON and SHOWOFF statements can be used to turn on and off showing information to the screen while allowing that same information (even if not displayed or transmitted via modem) to be captured to a file. The SHOWSTAT() function can be used to check the current status of the SHOWON and SHOWOFF statements. Examples BOOLEAN ss LET ss = SHOWSTAT() SHOWOFF OPENCAP "CAP"+STRING(PCBNODE()),ocFlag IF (ocFlag) THEN DIR "U;NS" CLOSECAP KBDSTUFF "FLAG CAP"+STRING(PCBNODE())+CHR(13) ENDIF IF (ss) THEN SHOWON ELSE SHOWOFF ENDIF See Also OPENCAP Statement, SHOWOFF Statement, SHOWON Statement, SHOWSTAT() Function CLREOL Statement Function Clear the current line from the cursor to the end of the line using the current color. Syntax CLREOL No arguments are required Remarks This statement will work one of two ways depending on the mode the caller is in. If the caller is in graphics mode (or non- graphics ANSI-positioning) then PCBoard will issue the ANSI sequence to clear to the end of the line using the current color. ANSI emulators, when written properly, will echo the color all the way to column 80 of the current line when they receive this ANSI sequence. If the user is in non-graphics non- ANSI mode, PCBoard will write sufficient spaces to the display to move to column 80 and then backspace to the original position. Note that this will not clear the 80th column; the reason for this is to always keep the cursor on the current line. If the cursor wrote a space to column 80 and moved to the beginning of the next line it wouldn't be able to move back up to the previous line without ANSI (which we already know we don't have). This should be adequate for most applications. Examples COLOR @X47 CLS PRINT "This is some sample text. (This will disappear.)" WHILE (INKEY() = "") DELAY 1 BACKUP 22 COLOR @X1F CLREOL PRINT "This goes to the end of the line." See Also CLS Statement CLS Statement Function Clear the screen using the current color. Syntax CLS No arguments are required Remarks This statement will work one of two ways depending on the mode the caller is in. If the caller is in graphics mode (or non- graphics ANSI-positioning) then PCBoard will issue the ANSI sequence to clear to the screen using the current color. If the user is in non-graphics non-ANSI mode, PCBoard will write send an ASCII 12 (form feed) character to the remote terminal in a last ditch effort to clear the remote callers screen. Many terminal programs do support this, but not all, so be aware that callers may see the ASCII 12 instead of a clear screen. Examples COLOR @X47 CLS PRINT "This is some sample text. (This will disappear.)" WHILE (INKEY() = "") DELAY 1 BACKUP 22 COLOR @X1F CLREOL PRINT "This goes to the end of the line." See Also CLREOL Statement COLOR Statement Function Change the current active color. Syntax COLOR newcolor newcolor An integer expression containing the new color to be used by PCBoard and the remote terminal software. Remarks This statement will change the color in use by PCBoard and send the appropriate ANSI sequence to change color to the remote terminal software. Note that this statement will only affect a color change if the user is in graphics mode. If the user is in non-graphics mode this statement will be ignored. Examples COLOR @X47 CLS PRINT "This is some sample text. (This will disappear.)" WHILE (INKEY() = "") DELAY 1 BACKUP 22 COLOR @X1F CLREOL PRINT "This goes to the end of the line." See Also DEFCOLOR Statement, DEFCOLOR() Function CONFFLAG Statement Function Set specified flags in the current conference for the current user. Syntax CONFFLAG confnum,flags confnum An integer expression containing the conference number to affect. flags An integer expression containing the flags to set. Remarks Each user on the BBS has a set of five flags for each conference that control various settings. These flags control the users registration in a conference, their expired status in a conference, whether or not they have a conference selected, whether or not they have mail waiting in a conference, and whether or not they have SysOp priviledges in a conference. Any or all of these flags may be set at once. To assist you in using this statement, five predefined constants are available to specify each flag: F_REG, F_EXP, F_SEL, F_MW, and F_SYS. To use these constants simply add the ones you need together. Examples ' Automatically register them in selected conferences INTEGER i FOR i = 1 TO 10 CONFFLAG i,F_REG+F_EXP+F_SEL NEXT FOR i = 11 TO 20 CONFFLAG i,F_REG+F_SEL NEXT See Also CONFUNFLAG Statement, F_EXP Constant, F_MW Constant, F_REG Constant, F_SEL Constant, F_SYS Constant CONFUNFLAG Statement Function Clear specified flags in the current conference for the current user. Syntax CONFUNFLAG confnum,flags confnum An integer expression containing the conference number to affect. flags An integer expression containing the flags to clear. Remarks Each user on the BBS has a set of five flags for each conference that control various settings. These flags control the users registration in a conference, their expired status in a conference, whether or not they have a conference selected, whether or not they have mail waiting in a conference, and whether or not they have SysOp priviledges in a conference. Any or all of these flags may be cleared at once. To assist you in using this statement, five predefined constants are available to specify each flag: F_REG, F_EXP, F_SEL, F_MW, and F_SYS. To use these constants simply add the ones you need together. Examples ' Automatically deregister them from selected conferences INTEGER i FOR i = 1 TO 10 CONFUNFLAG i,F_REG+F_EXP+F_SEL NEXT FOR i = 11 TO 20 CONFUNFLAG i,F_REG+F_SEL NEXT See Also CONFFLAG Statement, F_EXP Constant, F_MW Constant, F_REG Constant, F_SEL Constant, F_SYS Constant CURCOLOR() Function Function Returns the color in use by the ANSI driver. Syntax CURCOLOR() No arguments are required Return Type & Value INTEGER Returns the color code most recently issued to the ANSI driver. Remarks The @X code processor within PCBoard has the ability to save and restore color codes built in. PCBoard accomplishes this by saving the current color whenever it encounters an @X00 and reissuing the color change when it encounters an @XFF. Unfortunately, PCBoard will only remember one color at a time. With this function you can save and restore as many colors as your application needs. Examples INTEGER cc,x,y COLOR @X0F ANSIPOS 26,23 PRINT "Hit the SPACE BAR to continue" WHILE (KINKEY() <> " ") DO CLS LET x = 1+RANDOM(57) LET y = 1+RANDOM(21) PUSH 1+RANDOM(14) GOSUB sub LET cc = CURCOLOR() PUSH @X0F GOSUB sub PUSH cc GOSUB sub ANSIPOS 1,y CLREOL ENDWHILE :sub INTEGER c POP c COLOR c ANSIPOS x,y PRINT "PCBoard 15.0 with PPL!" DELAY 18 RETURN See Also CURCONF() Function Function Get the current conference number. Syntax CURCONF() No arguments are required Return Type & Value INTEGER Returns an integer with the current conference number. Remarks This function can be useful in configuring a PPL program to work in different ways in different conferences. As a quick example, we have a PPE file on Salt Air that interfaces with the enter message command. If a user is in certain conferences we prompt them for additional information that we will likely need, otherwise we skip to the normal enter message process. Of course, that's just one example; you are sure to have other uses for it. Examples IF (CURCONF() = 6) THEN ' The Salt Air beta conference is 6 PRINTLN "You are leaving a message in the beta conference." PRINTLN "Be sure to leave your file date and time" PRINTLN "and a complete description of the problem." ENDIF KBDSTUFF TOKENSTR() See Also CURSEC() Function Function Get the users current security level. Syntax CURSEC() No arguments are required Return Type & Value INTEGER Returns an integer with the current security level of the user. Remarks Although the users primary security level may be accessed via the U_SEC variable after using the GETUSER statement, it is often necessary to know the users security level right now after taking into account whether or not they have expired access, additional security from joining a specific conference, or additional security from the keyboard. This function will take all variables into account and return the current 'logical' security level. Examples IF (CURSEC() < 100) PRINTLN "Insufficient security!" See Also DATE Type Function Declare one or more variables of type date. Syntax DATE var|arr(s[,s[,s]])[,var|arr(s[,s[,s]])] var The name of a variable to declare. Must start with a letter [A-Z] which may be followed by letters, digits [0-9] or the underscore [_]. May be of any length but only the first 32 characters are used. arr The name of an array variable to declare. The same naming conventions as var are used. s The size (0-based) of an array variable dimension. Any constant integer expression is allowed. Remarks DATE variables are stored as julian dates. Valid dates are 0 (a special case to represent an invalid date) and 1 (1 JAN 1900) through 36524 (31 DEC 1999) through 65535 (5 JUN 2079). It is stored internally as a two byte unsigned integer. If a DATE is assigned to or from an INTEGER type then the julian date (0- 65535) is assigned. If a DATE is assigned to a STRING type then it is automatically converted to the following format: "MM/DD/YY", where MM is the two digit month (01-12), DD is the two digit day of the month (01-31), and YY is the two digit year (00-99). If a foreign language is in use that uses a different date format (for example, "DD/MM/YY" or "YY.MM.DD") then that will be taken into account. If a STRING is assigned to a DATE then PPL will do it's best to convert the string back to the appropriate julian date. However, dates before 1980 will not be handled correctly because only a two digit year is used in strings. All other types, when assigned to or from a DATE, will be converted to an INTEGER first before being assigned to or from the DATE type. Examples DATE dob, today, range(2), leapYears(50) See Also BOOLEAN Type, INTEGER Type, MONEY Type, STRING Type, TIME Type DATE() Function Function Get today's date. Syntax DATE() No arguments are required Return Type & Value DATE Returns a date for today. Remarks The date returned is represented internally in a julian format (the number of days since January 1, 1900). It may be used as is (for display, storage or as an argument to another function or statement) or assigned to an integer for arithmetic purposes. Examples PRINTLN "Today is ",DATE() See Also DAY() Function Function Extracts the day of the month from a date. Syntax DAY(dexp) dexp Any date expression. Return Type & Value INTEGER Returns the day of the month from the specified date expression (dexp). Valid return values are from 1 to 31. Remarks This function allows you to extract a particular piece of information about a DATE value, in this case the day of the month of the date. Examples PRINTLN "Today is: ",DAY(DATE()) See Also DOW() Function, MONTH() Function, YEAR() Function DBGLEVEL Statement Function Set a new debug level for PCBoard. Syntax DBGLEVEL level level An integer expression with the new debug level. Remarks PCBoard supports an internal variable that allows debug information to be written to the callers log. Level 0 specified no debug information. Levels 1 through 3 specify different (increasing) levels of debug information. It can also be useful for debugging your PPL programs. This statement allows you to change the PCBoard debug level on the fly without the need to have the SysOp exit and change it in the BOARD.BAT file. Examples INTEGER newlvl INPUT "New level",newlvl NEWLINE DBGLEVEL newlvl See Also DBGLEVEL() Function, LOG Statement DBGLEVEL() Function Function Returns the debug level in effect. Syntax DBGLEVEL() No arguments are required Return Type & Value INTEGER Returns the current debug level. Remarks PCBoard supports an internal variable that allows debug information to be written to the callers log. Level 0 specified no debug information. Levels 1 through 3 specify different (increasing) levels of debug information. It can also be useful for debugging your PPL programs. Using this function you can tie your debug information to a specified debug level of your choosing. Examples IF (DBGLEVEL() = 1) LOG "Writing DEBUG info for "+PPENAME(),0 See Also DBGLEVEL Statement, LOG Statement DEC Statement Function Decrement the value of a variable. Syntax DEC var var The variable with the value to decrement. Remarks Many programs require extensive addition and subtraction, and most often, a value is increased or decreased by 1. This statement allows for a shorter, more efficient method of decreasing (decrementing) a value by 1 than subtracting 1 from a variable and assigning the result to the same variable. Examples INTEGER i PRINTLN "Countdown:" LET i = 10 WHILE (i >= 0) DO PRINTLN "T minus ",i DEC i ENDWHILE See Also INC Statement DEFCOLOR Statement Function Change the current color to the system default color. Syntax DEFCOLOR No arguments are required Remarks This statement will change the color in use by PCBoard to the system default and send the appropriate ANSI sequence to change color to the remote terminal software. This statement is equivalent to COLOR DEFCOLOR(). Note that this statement will only affect a color change if the user is in graphics mode. If the user is in non-graphics mode this statement will be ignored. Examples COLOR @X47 CLS PRINT "This is some sample text. (This will disappear.)" WHILE (INKEY() = "") DELAY 1 BACKUP 22 DEFCOLOR CLREOL PRINT "This goes to the end of the line." See Also COLOR Statement, DEFCOLOR() Function DEFCOLOR() Function Function Return the system default color. Syntax DEFCOLOR() No arguments are required Return Type & Value INTEGER Returns the system default color as defined in PCBSetup. Remarks This function is useful in cases where you must pass a color to a statement but you want to honor the SysOp's choice of default color for the system. In that case you cannot use the DEFCOLOR statement because it does not return a value that you can pass to another statement. Examples STRING yn DEFCOLOR CLS LET yn = YESCHAR() INPUTYN "Continue",yn,DEFCOLOR() IF (yn = NOCHAR()) END See Also COLOR Statement, DEFCOLOR Statement DEFS Constant Function Used when no special statement parameters or flags are needed and defaults are sufficient. Value 0 = 0b = 0o = 0h Remarks There are many statements that take special values as parameters or flags as an indication to do some special processing. This constant is meant to be used by itself when you do not need any other special constant value. Examples STRING ans LET ans = NOCHAR() INPUTSTR "Run program now",ans,@X0E,1,"YyNn",DEFS IF (UPPER(ans) = NOCHAR()) END See Also DELAY Statement Function Pause execution for a specified period of clock ticks. Syntax DELAY ticks ticks An integer expression with the number of clock ticks to pause. Remarks It is often desireable to wait for a precise time interval for various purposes. This function will allow you to specify an interval to delay in clock ticks. One clock tick is approximately 1/18.2 of a second. So to delay for approximately one second, you should use DELAY 18. The basic formula to use is (seconds to delay*18.2) and then round off to the nearest whole number. Note however that PPL doesn't support floating point arithmetic, so if you want to calculate the delay interval at run time you should use something like (seconds to delay*182)/10. Examples INTEGER i PRINTLN "Countdown:" LET i = 10 WHILE (i >= 0) DO PRINTLN "T minus ",i DEC i DELAY 18 ENDWHILE See Also DELETE Statement Function Delete a specified file from the disk it resides on. Syntax DELETE file file A string expression with the drive, path and file name to delete. Remarks It is always a good idea to leave things as you found them (as much as possible). This statement allows you to delete temporary files created by your PPE with the FCREATE/FOPEN/FAPPEND statements. Examples INTEGER retcode STRING s FCREATE 1,"TMP.LST",O_WR,S_DB LET s = "START" WHILE (LEN(s) > 0) DO LET s = "" PRINTLN "Enter a name or ENTER alone to quit:" INPUT "Name",s IF (LEN(s) > 0) FPUTLN 1,s ENDWHILE FCLOSE 1 SHELL 1,retcode,"SORT","< TMP.LST > TMP.SRT" NEWLINE PRINTLN "Unsorted List:" PRINTLN "--------------" DISPFILE "TMP.LST",DEFS NEWLINE PRINTLN "Sorted List:" PRINTLN "--------------" DISPFILE "TMP.SRT",DEFS DELETE "TMP.LST" DELETE "TMP.SRT" See Also RENAME Statement DELUSER Statement Function Flag the user online on the current node for deletion. Syntax DELUSER No arguments are required Remarks This statement will set the delete user record flag to TRUE. This will merely flag PCBSystemManager to pack out the user during the next pack operation. If you want to make sure the user doesn't log back in before being packed out, use GETUSER, set his U_SEC and U_EXPSEC variables to 0, and use the PUTUSER statement to write the changes to the user record. Examples GETUSER IF (U_CMNT2 = "BAD USER") THEN PRINTLN "Just a friendly note to say," PRINTLN "I hope you have a rotten day!" PRINTLN "Proceeding with automatic user record deletion..." DELUSER LET U_SEC = 0 LET U_EXPSEC = 0 PUTUSER ENDIF See Also DIR Statement Function Execute the file directories command with desired sub-commands. Syntax DIR cmds cmds A string expression with any desired sub-commands for the file directory command. Remarks This statement will allow you to access file directories (the F command from the main menu), and any file directory sub- commands, under PPE control. Note that this statement will destroy any previously tokenized string expression. If you have string tokens pending at the time of the DIR statment you should save them first and then retokenize after the DIR statement is complete. Examples INTEGER retcode SHOWOFF OPENCAP "NEWFILES.LST",retcode KBDSTUFF CHR(13) DIR "N;S;A;NS" CLOSECAP SHOWON SHELL TRUE,retcode,"PKZIP","-mex NEWFILES NEWFILES.LST" KBDSTUFF "FLAG NEWFILES.ZIP" See Also DISPFILE Statement Function Display a specified (or alternate) file. Syntax DISPFILE file,flags file A string expression with the file name (or base file name) to display. flags An integer expression with alternate file flags. Remarks This statement will allow you to display a file to the user, and optionally to have PCBoard look for alternate security, graphics, and/or language specific files. The flags parameter should be 0 for no alternate searching, GRAPH (1) for graphics specific searching, SEC (2) for security specific searching, LANG (4) for language specific searching, or any combination thereof for multiple alternate searches simultaneously. Examples STRING s DISPFILE "MNUA",SEC+GRAPH+LANG INPUT "Option",s See Also DISPSTR Statement Function Display a string of text. Syntax DISPSTR str str A string expression to display (or %filename or !PPEfile to execute). Remarks This statement in intended to allow you to easily display a string to the user and provide some of the functionality of PCBTEXT. If the string to display begins with a percent sign and is followed by a valid file name, then the file will be displayed to the caller instead of the string. Alternately, the string could begin with an exclamation mark (and be followed by a legal filename) to run a PPE file. Examples STRING s INPUT "String",s DISPSTR s LET s = "Regular string" DISPSTR s DISPSTR "%C:\PCB\GEN\BRDM" DISPSTR "!"+PPEPATH()+"SUBSCR.PPE" See Also DISPTEXT Statement Function Display a specified prompt from the PCBTEXT file. Syntax DISPTEXT rec,flags rec An integer expression with the PCBTEXT record number to display. flags An integer expression with display flags. Remarks This statement will allow you to display any prompt from the PCBTEXT file to the user according to a set of display flags. Valid display flags are BELL, DEFS, LFAFTER, LFBEFORE, LOGIT, LOGITLEFT, and NEWLINE. Examples DISPTEXT 192,BELL+NEWLINE+LOGIT HANGUP See Also DOINTR Statement Function Generate a system interrupt. Syntax DOINTR int,ax,bx,cx,dx,si,di,flags,ds,es int An integer expression with the interrupt number to call (0 through 255). others Integer expressions with 16-bit register values to pass to the interrupt (ax, bx, cx, dx, si, and di are general purpose registers; ds and es are segment registers; flags is the 80x86 processor status register). Remarks This statement allows practically unlimited flexibility in PPL. It allows you to access any system service available via the BIOS (video, disk, time, etc), DOS or other third party interface (DESQview, NETBIOS, IPX/SPX, Btrieve, etc). The possibilities are limited only by your imagination. Values that are returned via register may be accessed via the REG...() functions. The values to pass to specific interrupts will vary by the interrupt and function desired. WARNING!!! The DOINTR function can be a very valuable tool when used wisely; it can also be extremely destructive when used improperly (either accidentally or intentionally). Use it at your own risk! Examples ' Create subdirectory - DOS function 39h INTEGER addr STRING path LET path = "C:\$TMPDIR$" VARADDR path,addr DOINTR 21h,39h,0,0,addr%00010000h,0,0,0,addr/00010000h,0 IF (REGCF() & (REGAX() = 3)) THEN PRINTLN "Error: Path not found" ELSE IF (REGCF() & (REGAX() = 5)) THEN PRINTLN "Error: Access Denied" ELSE IF (REGCF()) THEN PRINTLN "Error: Unknown Error" ELSE PRINTLN "Directory successfully created..." ENDIF See Also B2W() Function, REG...() Function, VARADDR Statement, VAROFF Statement, VARSEG Statement DOW() Function Function Determine the day of the week of a particular date. Syntax DOW(dexp) dexp Any date expression. Return Type & Value INTEGER Returns the day of the week from the specified date expression (dexp). Valid return values are from 0 (Sunday) to 6 (Saturday). Remarks This function allows you to extract a particular piece of information about a DATE value, in this case the day of the week of the date. The specified date can be any valid DATE expression. Examples PRINTLN "Today is: ",DOW(DATE()) See Also DAY() Function, MONTH() Function, YEAR() Function DTROFF Statement Function Turn off the serial port DTR signal. Syntax DTROFF No arguments are required Remarks This statement turns off the serial port DTR signal. Most modems take this condition to mean that they should hang up on a caller, and this is how PCBoard uses it. This statement can be used when you need to hangup on a caller but don't want PCBoard to perform it's logoff processing. Simply turn off CD checking and keyboard timeout checking and issue the DTROFF statement. Do whatever processing you want, then turn DTR, keyboard timeout testing, and CD loss testing back on to allow PCBoard to recycle normally. Note that DTR should remain off for a period of time to ensure that the modem has time to react to it. Consider 1/2 second (about 9 clock ticks) a reasonable delay. Examples BOOLEAN flag KBDCHKOFF CDCHKOFF DTROFF DELAY 18 DTRON SENDMODEM "ATDT5551212" ' Please don't really dial this number! WAITFOR "CONNECT",flag,60 IF (!flag) SPRINLN "No connect found in 60 seconds" CDCHKON KBDCHKON See Also DTRON Statement DTRON Statement Function Turn on the serial port DTR signal. Syntax DTRON No arguments are required Remarks This statement turns on the serial port DTR signal. This statement should be used after you've used the DTROFF statement to hangup the modem when you need to hangup on a caller but don't want PCBoard to perform it's logoff processing. Note that DTR should remain off for a period of time, to ensure that the modem has time to react to it, before turning it back on. Consider 1/2 second (about 9 clock ticks) a reasonable delay. Examples BOOLEAN flag KBDCHKOFF CDCHKOFF DTROFF DELAY 18 DTRON SENDMODEM "ATDT5551212" ' Please don't really dial this number! WAITFOR "CONNECT",flag,60 IF (!flag) SPRINLN "No connect found in 60 seconds" CDCHKON KBDCHKON See Also DTROFF Statement ECHODOTS Constant Function Set the echo dots flag in an INPUTSTR or PROMPTSTR statement. Value 1 = 1b = 1o = 1h Remarks The INPUTSTR and PROMPTSTR statements have the ability to disable echoing of user input and instead echo dots in place of the user's input. This is useful in situations where the information being entered is confidential and shouldn't be revealed to any other party. A good example of this is the user's password. Examples STRING pwd PROMPTSTR 148,pwd,12,MASK_PWD(),ECHODOTS+UPCASE GETUSER IF (pwd <> U_PWD) HANGUP See Also INPUTSTR Statement, PROMPTSTR Statement END Statement Function Terminate PPE execution. Syntax END No arguments are required Remarks This statement may be used to normally terminate PPE execution at any point. If you do not have one in your program one is automatically inserted at the end of your source for you at compile time. Additionally, if your PPL application is being used as a script questionnaire, this statement will save any responses written to channel 0 to the script answer file. Examples DATE d INTEGER i STRING s LET s = "01-20-93" LET d = s IF (DATE() < d) THEN PRINTLN "Your calendar is off!" END ENDIF LET i = d PRINTLN "The seige continues: Day ",DATE()-i+1 END See Also RETURN Statement, STOP Statement ERASELINE Constant Function Set the erase line flag in an INPUTSTR or PROMPTSTR statement. Value 32 = 100000b = 40o = 20h Remarks The INPUTSTR and PROMPTSTR statements have the ability to erase the current line after the user presses ENTER. This is the technique used by the MORE and WAIT statements to clean up after themselves. Examples STRING s INPUTSTR "Press ENTER to continue",s,@X0E,0,"",ERASELINE See Also INPUTSTR Statement, PROMPTSTR Statement EXIST() Function Function Determine whether or not a file exists. Syntax EXIST(file) file A string expression with the drive, path and file name to check. Return Type & Value BOOLEAN Returns TRUE if the file exists on the specified drive and path, FALSE otherwise. Remarks It is often necessary to check for the existence of a file. For example, you wouldn't want to display or otherwise process a file that doesn't exist. This function will report whether or not a specified file exists on a particular drive and path. The drive will default to the current drive and the path will default to the current directory if not specified. Examples STRING file LET file = "NEWS."+STRING(CURNODE()) IF (EXIST(file)) DISPFILE file,0 See Also FILEINF() Function FALSE Constant Function To provide a named constant for the boolean false value in boolean expressions. Value 0 = 0b = 0o = 0h Remarks BOOLEAN logic is based on two values: TRUE (1) and FALSE (0). The literal numeric constants 0 and 1 may be used in expressions, or you may use the predefined named constants TRUE and FALSE. They make for more readable, maintainable code and have no more overhead than any other constant value at run time. Examples BOOLEAN flag LET flag = TRUE WHILE (!flag) DO INPUTSTR "Text",s,@X0E,60,"ABCDEFGHIJKLMNOPQRSTUVWXYZ ",UPCASE PRINTLN s IF (s = "QUIT") LET flag = FALSE ENDWHILE See Also TRUE Constant FAPPEND Statement Function Open a file for append access. Syntax FAPPEND chan,file,am,sm chan An integer expression with the channel to use for the file (0 through 7). file A string expression with the file specification to open. am An integer expression with the desired access mode for the file. sm An integer expression with the desired share mode flags for the file. Remarks This statement allows a PPL application to open a file for append access. Often you need to add information to an existing file without destroying the existing information in the file. FCREATE completely destroys the file being opened if it already exists, and FOPEN will simply position you at the beginning of the file where you would overwrite data. This statement will allow you to add the necessary information to the end of a file without destroying the file or any existing information in the file. The chan parameter must be 0 through 7; 0 is reserved for the answer file when a PPL script questionnaire is in use but is available for all other applications. However, it is recommended you avoid channel 0 unless you really need to open 8 files at once. The am parameter should be one of the following constant values: O_RD (for read access), O_WR (for write access), or O_RW (for read/write access). Note that the FAPPEND statement actually requires O_RW access; whatever you specify doesn't really matter as it will be overridden by PPL, but you must specify it to maintain compatibility with the FCREATE and FOPEN statements. Finally, the sm parameter should be one of the following constants: S_DN (for deny none sharing), S_DR (for deny read sharing), S_DW (for deny write sharing), or S_DB (for deny both sharing). Also, if the file specified doesn't exist, it will automatically be created. Examples FAPPEND 1,"C:\PCB\MAIN\PPE.LOG",O_RW,S_DB FPUTLN 1,"Ran "+PPENAME()+" on "+STRING(DATE())+" at "+STRING(TIME()) FCLOSE 1 See Also FCLOSE Statement, FCREATE Statement, FOPEN Statement, FREWIND Statement FCL Constant Function Forces PCBoard to count lines and provide prompts after every screen full of information. Value 2 = 10b = 2o = 2h Remarks The STARTDISP statement takes a single argument to start displaying information in a certain format. FCL tells PCBoard to count lines and pause as needed during the display of information. FNS tells PCBoard to not stop during the display of information. NC instructs PCBoard to start over with the last specified mode (FCL or FNS). Examples INTEGER i STARTDISP FCL FOR i = 1 to 100 PRINTLN "This is line ",i NEXT See Also FNS Constant, NC Constant FCLOSE Statement Function Close an open file. Syntax FCLOSE chan chan An integer expression with the open channel to close (0 through 7). Remarks This statement should be used to close a file channel after it has been created/opened with an FCREATE, FOPEN, or FAPPEND statement. If you should forget to close your files by the end of your PPL application, PPL will automatically close them for you. However, if you need to process many files, it will usually be required that you open a few at a time and close them before going on to the next set of files. Examples FOPEN 1,"C:\PCB\MAIN\PPE.LOG",O_RD,S_DW FGET 1,hdr FCLOSE 1 IF (hdr <> "Creating PPE.LOG file . . .") THEN PRINTLN "Error: PPE.LOG invalid" END ENDIF See Also FAPPEND Statement, FCREATE Statement, FOPEN Statement, FREWIND Statement FCREATE Statement Function Create and open a file. Syntax FCREATE chan,file,am,sm chan An integer expression with the channel to use for the file (0 through 7). file A string expression with the file specification to create and open. am An integer expression with the desired access mode for the file. sm An integer expression with the desired share mode flags for the file. Remarks This statement allows a PPL application to force the creation and opening of a file, even if it already exists. Creation means that any information previously in the file (if it already exists) will be lost and you will be starting over with an empty file. The chan parameter must be 0 through 7; 0 is reserved for the answer file when a PPL script questionnaire is in use but is available for all other applications. However, it is recommended you avoid channel 0 unless you really need to open 8 files at once. The am parameter should be one of the following constant values: O_RD (for read access), O_WR (for write access), or O_RW (for read/write access). Note that the FCREATE statement forces the creation of an empt file so it doesn't make much sense to use O_RD, as there is nothing to read, unless you only want to create the file. Finally, the sm parameter should be one of the following constants: S_DN (for deny none sharing), S_DR (for deny read sharing), S_DW (for deny write sharing), or S_DB (for deny both sharing). Examples FCREATE 1,"C:\PCB\MAIN\PPE.LOG",O_WR,S_DN FPUTLN 1,"Creating PPE.LOG file . . ." FCLOSE 1 See Also FAPPEND Statement, FCLOSE Statement, FOPEN Statement, FREWIND Statement FERR() Function Function Determine whether or not an error has occurred on a channel since last checked. Syntax FERR(chan) chan An integer expression with the channel to use for the file (0 through 7). Return Type & Value BOOLEAN Returns TRUE if an error has occurred on the specified channel since last checked, FALSE otherwise. Remarks There are many reasons why errors can occur during file processing. The drive, path or file may not exist, the end of the file may have been reached, the drive may be full, there could be errors with the hardware, and so on. For maximum reliability, you should use the function to check for errors after every file channel statement. PCBoard will automatically handle alerting the user of the error in most cases. All you need is to know that an error occurred so that you may continue processing else where or clean up and exit. Examples INTEGER i STRING s FOPEN 1,"FILE.DAT",O_RD,S_DW IF (FERR(1)) THEN PRINTLN "Error, exiting..." END ENDIF FGET 1,s WHILE (!FERR(1)) DO INC i PRINTLN "Line ",RIGHT(i,3),": ",s FGET 1,s ENDWHILE FCLOSE 1 See Also FGET Statement Function Get (read) a line from an open file. Syntax FGET chan,var chan An integer expression with the channel to read from (0 through 7). var The variable into which to read the next line from chan. Remarks This statement is to be used for reading information, a line at a time, from a file that was previously opened with read access. If there are multiple items of information on the line then you must parse them out manually. Examples INTEGER i STRING s FOPEN 1,"FILE.DAT",O_RD,S_DW IF (FERR(1)) THEN PRINTLN "Error, exiting..." END ENDIF FGET 1,s WHILE (!FERR(1)) DO INC i PRINTLN "Line ",RIGHT(i,3),": ",s FGET 1,s ENDWHILE FCLOSE 1 See Also FPUT/FPUTLN Statements, FPUTPAD Statement FIELDLEN Constant Function Set the display field length flag in an INPUTSTR or PROMPTSTR statement. Value 2 = 10b = 2o = 2h Remarks The INPUTSTR and PROMPTSTR statements have the ability to display the length of an input field using "( )" if the user has ANSI available. If you want to ensure that the user knows how wide the input area is regardless of ANSI support being available, also use the GUIDE constant. Examples STRING pwd INPUTSTR "Enter id number",pwd,@X0E,4,"0123456789",FIELDLEN+GUIDE IF (pwd <> "1234") PRINTLN "Bad id number" See Also GUIDE Constant, INPUTSTR Statement, PROMPTSTR Statement FILEINF() Function Function Access a piece of information about a file. Syntax FILEINF(file,item) file A string expression with the path and file name to access information about. item An integer expression with the desired piece of information (1 through 9) to retrieve about file. Return Type & Value BOOLEAN Returns TRUE if file exists or FALSE if file doesn't exist if item is 1. DATE Returns the date stamp of file if item is 2. INTEGER Returns one of the following for the specified values of stat: 4 The size of file in bytes; 5 The attribute bits of file. STRING Returns one of the following for the specified values of stat: 6 The drive of file; 7 The path of file; 8 The base name of file; 9 The extension of file. TIME Returns the time stamp of file if item is 3. Remarks This function is designed to return information about a file. The file date, time, size and attributes are accessible from DOS. In addition, this function can parse out the drive, path, base name and extension if needed from the complete file specification. Finally, the EXIST() function is duplicated in FILEINF(). Examples STRING file WHILE (FILEINF(file,1)) INPUT "File",file PRINTLN " Date: ",FILEINF(file,2) PRINTLN " Time: ",FILEINF(file,3) PRINTLN " Size: ",FILEINF(file,4) PRINTLN " Attr: ",FILEINF(file,5) PRINTLN "Drive: ",FILEINF(file,6) PRINTLN " Path: ",FILEINF(file,7) PRINTLN " Name: ",FILEINF(file,8) PRINTLN " Ext: ",FILEINF(file,9) See Also EXIST() Function FMTCC() Function Function Formats a credit card number for display purposes. Syntax FMTCC(sexp) sexp Any string expression. Return Type & Value STRING Returns sexp formatted in a credit card style for display purposes. Remarks This function will do one of the following: one, take a 13 character string and format it as "XXXX XXX XXX XXX"; two, take a 15 character string and format it as "XXXX XXXXXX XXXXX"; three, take a 16 character string and format it as "XXXX XXXX XXXX XXXX"; or four, return the string unmodified if it is not 13, 15 or 16 characters long. Examples STRING s WHILE (!VALCC(s)) DO INPUT "CC #",s NEWLINES 2 ENDWHILE PRINTLN CCTYPE(s)," - ",FMTCC(s) See Also CCTYPE() Function, VALCC() Function, VALDATE() Function, VALTIME() Function FNS Constant Function Forces PCBoard to not stop to provide prompts while displaying information. Value 1 = 1b = 1o = 1h Remarks The STARTDISP statement takes a single argument to start displaying information in a certain format. FCL tells PCBoard to count lines and pause as needed during the display of information. FNS tells PCBoard to not stop during the display of information. NC instructs PCBoard to start over with the last specified mode (FCL or FNS). Examples INTEGER i STARTDISP FNS FOR i = 1 to 100 PRINTLN "This is line ",i NEXT See Also FCL Constant, NC Constant FOPEN Statement Function Open a file. Syntax FOPEN chan,file,am,sm chan An integer expression with the channel to use for the file (0 through 7). file A string expression with the file specification to open. am An integer expression with the desired access mode for the file. sm An integer expression with the desired share mode flags for the file. Remarks This statement allows a PPL application to open a file for read and/or write access and to specify the method of sharing desired. The chan parameter must be 0 through 7; 0 is reserved for the answer file when a PPL script questionnaire is in use but is available for all other applications. However, it is recommended you avoid channel 0 unless you really need to open 8 files at once. The am parameter should be one of the following constant values: O_RD (for read access), O_WR (for write access), or O_RW (for read/write access). Note that the O_RD constant expects the file to already exist; the other open constants will create the file if it already doesn't exist. Finally, the sm parameter should be one of the following constants: S_DN (for deny none sharing), S_DR (for deny read sharing), S_DW (for deny write sharing), or S_DB (for deny both sharing). Examples STRING hdr FOPEN 1,"C:\PCB\MAIN\PPE.LOG",O_RD,S_DW FGET 1,hdr FCLOSE 1 IF (hdr <> "Creating PPE.LOG file . . .") THEN PRINTLN "Error: PPE.LOG invalid" END ENDIF See Also FAPPEND Statement, FCLOSE Statement, FCREATE Statement, FREWIND Statement FOR/NEXT Statement Function Execute a block of statments for a range of values. Syntax FOR var = start TO end [STEP inc] s t a t e m e n t ( s ) NEXT var The index variable for the loop that will be set to each value. start Any valid PPL expression. end Any valid PPL expression. inc Any valid PPL expression. 1 if not specified. Remarks A FOR loop can consist of one or more statements. At the beginning of the loop the specified variable (var) is initialized to the start value. It is then checked against the end value. If start is greater than end (for positive values of inc) or less than end (for negative values of inc) then the loop terminates. Otherwise all the statements in the loop are executed in order. At the NEXT statement the inc value (1 if not explicitly defined) is added to var and the loop value is retested as described above. Examples BOOLEAN p(100) INTEGER i FOR i = 1 TO 100 ' Initialize all to TRUE LET p(i) = TRUE NEXT LET p(1) = FALSE FOR i = 4 TO 100 STEP 2 ' Initialize every other one to FALSE LET p(i) = FALSE NEXT See Also IF/ELSEIF/ELSE/ENDIF Statement, WHILE/ENDWHILE Statement FORWARD Statement Function Move the cursor forward a specified number of columns. Syntax FORWARD numcols numcols An integer expression of the number of columns to move forward. Valid values are 1 through 79. Remarks This statement will move the cursor forward, nondestructively, a specified number of columns. It will work with or without ANSI. If ANSI is available (as reported by the ANSION() function) then it will use an ANSI positioning command; otherwise it will re- display the specified number of characters that are already on screen. ANSI is usually faster, but re-displaying the existing information will get the job done. Note that you cannot use this function to move beyond column 80; to do so would require ANSI to move back up if necessary. So, if the cursor is already in column 80 this statement will have no effect. And if the cursor is in column 1 the maximum you could move forward would be 79 (column 1 + 79 columns = column 80). Examples PRINT "PIRNT is wrong" DELAY 5*182/10 BACKUP 13 PRINT "RI" FORWARD 6 PRINT "RIGHT" DELAY 5*182/10 NEWLINE WAIT See Also ANSION() Function, ANSIPOS Statement, BACKUP Statement, GETX() Function, GETY() Function, GRAFMODE() Function FPUT/FPUTLN Statements Function Put (write) a line to an open file (with an optional carriage return/line feed appended). Syntax F P U T c h a n , e x p [ , e x p ] - o r - FPUT chan[,exp[,exp]] chan An integer expression with the channel to write to (0 through 7). exp An expression of any type to evaluate and write to chan. Remarks These statements will evalutate zero, one or more expressions of any type and write the results to the specified channel number. The FPUTLN statement will append a carriage return/line feed sequence to the end of the expressions; FPUT will not. Note that at least one expression must be specified for FPUT, unlike the FPUTLN statement which need not have any arguments passed to it other than the channel number. Examples FAPPEND 1,"FILE.DAT",O_WR,S_DB FPUT 1,U_NAME()," ",DATE() FPUTLN 1," ",TIME()," ",CURSEC() FPUT 1,"Logged!" FPUTLN 1 FPUTLN 1,"Have a nice"+" day!" FCLOSE 1 See Also FGET Statement, FPUTPAD Statement FPUTPAD Statement Function Put (write) a line of a specified width to an open file. Syntax FPUT chan,exp,width chan An integer expression with the channel to write to (0 through 7). exp An expression of any type to evaluate and write to chan. width An integer expression with the width to use to write exp. Valid values are -256 through 256 Remarks This statement will evalutate an expressions of any type and write the result to the specified channel number. This statement will append a carriage return/line feed sequence to the end of the expression after padding it to the specified width with spaces. If width is positive, then exp will be written right justified (left padded) to the file. If width is negative, then exp will be written left justified (right padded) to the file. Examples FAPPEND 1,"FILE.DAT",O_WR,S_DB FPUTPAD 1,U_NAME(),40 FPUTPAD 1,U_DATE(),20 FPUTPAD 1,U_TIME(),20 FCLOSE 1 See Also FGET Statement, FPUT/FPUTLN Statements FRESHLINE Statement Function Move the cursor to a fresh line for output. Syntax FRESHLINE No arguments are required Remarks Often while displaying information to the screen you will print a certain amount then want to make sure you are on a clean line before continuing. This statement checks to see if you are in column 1 of the current line. If you are, it assumes you are on a clean line and does nothing. Otherwise, it calls the NEWLINE statement for you automatically. Examples INTEGER i, end LET end = RANDOM(20) FOR i = 1 TO end PRINT RIGHT(RANDOM(10000),8) NEXT FRESHLINE PRINTLN "Now we continue . . ." See Also NEWLINE Statement, NEWLINES Statement FREWIND Statement Function Rewind an open file. Syntax FREWIND chan chan An integer expression with the open channel to rewind (0 through 7). Remarks This statement should be used when you need to rewind a file channel after it has been created/opened with an FCREATE, FOPEN, or FAPPEND statement. Rewinding a file channel will flush file buffers, commit the file to disk, and reposition the file pointer to the beginning of the file. Useful when you need to start over processing a file that may have changed and don't want to close and re-open the file. Examples STRING s FAPPEND 1,"C:\PCB\MAIN\PPE.LOG",O_RW,S_DN FPUTLN 1,U_NAME() FREWIND 1 WHILE (!FERR(1)) DO FGET 1,s PRINTLN s ENDWHILE FCLOSE 1 See Also FAPPEND Statement, FCLOSE Statement, FCREATE Statement, FOPEN Statement F_EXP Constant Function Set the conference expired access flag in a CONFFLAG or CONFUNFLAG statement. Value 2 = 10b = 2o = 2h Remarks There are five flags per conference maintained for each user. This flag is used to indicate whether or not a user is registered in a specified conference after their subscription expiration date. Examples CONFUNFLAG 5,F_REG+F_EXP+F_SEL ' Clear reg, exp & sel flags from conf 5 CONFFLAG 9,F_REG+F_EXP+F_SEL ' Set reg, exp & sel flags for conf 9 See Also F_MW Constant, F_REGConstant, F_SEL Constant, F_SYS Constant F_MW Constant Function Set the conference mail waiting flag in a CONFFLAG or CONFUNFLAG statement. Value 10 = 10000b = 20o = 10h Remarks There are five flags per conference maintained for each user. This flag is used to indicate whether or not a user has mail waiting in a specified conference. Examples CONFUNFLAG 5,F_MW ' Clear mail waiting flag from conf 5 CONFFLAG 9,F_MW ' Set mail waiting flag for conf 9 See Also F_EXP Constant, F_REGConstant, F_SEL Constant, F_SYS Constant F_REG Constant Function Set the conference registration flag in a CONFFLAG or CONFUNFLAG statement. Value 1 = 1b = 1o = 1h Remarks There are five flags per conference maintained for each user. This flag is used to indicate whether or not a user is registered in a specified conference. Examples CONFUNFLAG 5,F_REG+F_EXP+F_SEL ' Clear reg, exp & sel flags from conf 5 CONFFLAG 9,F_REG+F_EXP+F_SEL ' Set reg, exp & sel flags for conf 9 See Also F_EXP Constant, F_MW Constant, F_SEL Constant, F_SYS Constant F_SEL Constant Function Set the conference selected flag in a CONFFLAG or CONFUNFLAG statement. Value 4 = 100b = 4o = 4h Remarks There are five flags per conference maintained for each user. This flag is used to indicate whether or not a user has a specified conference selected for message scans. Examples CONFUNFLAG 5,F_REG+F_EXP+F_SEL ' Clear reg, exp & sel flags from conf 5 CONFFLAG 9,F_REG+F_EXP+F_SEL ' Set reg, exp & sel flags for conf 9 See Also F_EXP Constant, F_MW Constant, F_REG Constant, F_SYS Constant F_SYS Constant Function Set the conference SysOp access flag in a CONFFLAG or CONFUNFLAG statement. Value 8 = 1000b = 10o = 8h Remarks There are five flags per conference maintained for each user. This flag is used to indicate whether or not a user has conference SysOp access in a specified conference. Examples CONFUNFLAG 5,F_SYS ' Remove (unflag) conf sysop access from conf 5 CONFFLAG 9,F_SYS ' Grant (flag) conf sysop access for conf 9 See Also F_EXP Constant, F_MW Constant, F_REG Constant, F_SEL Constant GETENV() Function Function Access the value of an environment variable. Syntax GETENV(name) name A string expression with the name of the environment variable to access. Return Type & Value STRING Returns the value of the environment variable specified by name. Remarks This function allows you to access the value of any environment variable set at the time that PCBoard was started. So, for example, the PATH environment variable could be used to access data files somewhere on the path. Examples STRING path LET path = GETENV() TOKENIZE path LET path = "DATAFILE.TXT" WHILE (!EXIST(path) & (TOKCOUNT() > 0)) DO LET PATH = GETTOKEN()+"DATAFILE.TXT" ENDWHILE IF (EXIST(path)) PRINTLN "Found ",path,"!" See Also GETTOKEN Statement Function Retrieve a token from a previous TOKENIZE statement. Syntax GETTOKEN var var Variable to store the retrieved token in. Remarks One of the strongest features of PCBoard is it's ability to take a series of stacked parameters from a command line and use them all at once instead of requiring the user to navigate a series of menus and select one option at each step of the way. The TOKENIZE statement is the PPL equivalent of what PCBoard uses to break a command line into individual commands (tokens). The number of tokens available may be accessed via the TOKCOUNT() function, and each token may be accessed, one at a time, by the GETTOKEN statement and/or the GETTOKEN() function. Examples STRING cmdline INPUT "Command",cmdline TOKENIZE cmdline PRINTLN "You entered ",TOKCOUNT()," tokens" WHILE (TOKCOUNT() > 0) DO GETTOKEN cmdline PRINTLN "Token: ",CHR(34),cmdline,CHR(34) ENDWHILE See Also GETTOKEN() Function, TOKCOUNT() Function, TOKENIZE Statement, TOKENSTR() Function GETTOKEN() Function Function Retrieve a token from a previous TOKENIZE statement. Syntax GETTOKEN() No arguments are required Return Type & Value STRING Returns the next available token from the most recent TOKENIZE statement. Remarks One of the strongest features of PCBoard is it's ability to take a series of stacked parameters from a command line and use them all at once instead of requiring the user to navigate a series of menus and select one option at each step of the way. The TOKENIZE statement is the PPL equivalent of what PCBoard uses to break a command line into individual commands (tokens). The number of tokens available may be accessed via the TOKCOUNT() function, and each token may be accessed, one at a time, by the GETTOKEN statement and/or the GETTOKEN() function. Examples STRING cmdline INPUT "Command",cmdline TOKENIZE cmdline PRINTLN "You entered ",TOKCOUNT()," tokens" WHILE (TOKCOUNT() > 0) DO LET cmdline = GETTOKEN() PRINTLN "Token: ",CHR(34),cmdline,CHR(34) ENDWHILE See Also GETTOKEN Statement, TOKCOUNT() Function, TOKENIZE Statement, TOKENSTR() Function GETUSER Statement Function Fill predeclared variables with values from user record. Syntax GETUSER No arguments are required Remarks There are many predeclared variables which may be used to access and change user information. However, their values are undefined until you use the GETUSER statement, and any changes you make don't take hold until you use the PUTUSER statement. Examples IF (PSA(3)) THEN GETUSER INPUT "Addr 1",U_ADDR(0) INPUT "Addr 2",U_ADDR(1) INPUT "City ",U_ADDR(2) INPUT "State ",U_ADDR(3) INPUT "ZIP ",U_ADDR(4) INPUT "Cntry ",U_ADDR(5) PUTUSER ENDIF See Also PUTUSER Statement GETX() Function Function Report the X coordinate (column) of the cursor on screen. Syntax GETX() No arguments are required Return Type and Value INTEGER Returns the column (1-80) of the cursor on screen. Remarks This function is used to query the ANSI emulator in PCBoard the current X position of the cursor. It may be used for saving the cursor position for future use or for saving the horizontal cursor position while changing the vertical position with the ANSIPOS statement. Examples INTEGER x,y STRING s WHILE (UPPER(s) <> "QUIT") DO INPUT "Text",s PRINTLN " - ",s LET x = GETX() LET y = GETY() IF (y = 23) THEN CLS LET x = GETX() LET y = GETY() ENDIF ANSIPOS 40,23 PRINT "@X8Fs=",s ANSIPOS x,y ENDWHILE See Also ANSIPOS Statement, ANSION() Function, BACKUP Statement, FORWARD Statement, GETY() Function, GRAFMODE() Function GETY() Function Function Report the Y coordinate (row) of the cursor on screen. Syntax GETY() No arguments are required Return Type and Value INTEGER Returns the row (1-23) of the cursor on screen. Remarks This function is used to query the ANSI emulator in PCBoard the current Y position of the cursor. It may be used for saving the cursor position for future use or for saving the verticle cursor position while changing the horizontal position with the ANSIPOS statement. Examples INTEGER x,y STRING s WHILE (UPPER(s) <> "QUIT") DO INPUT "Text",s PRINTLN " - ",s LET x = GETX() LET y = GETY() IF (y = 23) THEN CLS LET x = GETX() LET y = GETY() ENDIF ANSIPOS 40,23 PRINT "@X8Fs=",s ANSIPOS x,y ENDWHILE See Also ANSIPOS Statement, ANSION() Function, BACKUP Statement, FORWARD Statement, GETX() Function, GRAFMODE() Function GOODBYE Statement Function Log the user off as though they had typed the G (goodbye) command. Syntax GOODBYE No arguments are required Remarks There are multiple ways for the user to log off. One is by typing G at the command prompt. That will warn them if they have files flagged for download and (optionally) confirm their selection (incase they accidentally hit G and ENTER). Another is the BYE command. PCBoard assumes that, if the user typed BYE instead of G, that they really want to log off, didn't type it in accidentally, and want to leave now. The GOODBYE statement performs the same processing as the PCBoard G command. Examples STRING s INPUT "What do you want to do",s IF (s = "G") THEN GOODBYE ELSEIF (s = "BYE") THEN BYE ELSE KBDSTUFF s ENDIF See Also BYE Statement, HANGUP Statement GOSUB Statement Function Transfer program control and save the return information. Syntax GOSUB label label The label to which control should be transferred. Remarks It is often necessary to perform an indentical set of instructions several times in a program. This leaves you with two choices. One, rewrite the code several times (and hope you do it right each time), or two, write it once as a subroutine, then use GOSUB to run it. This statement will save the address of the next line so that a RETURN statement at the end of the subroutine can instruct PPL to resume execution with the line following the GOSUB. Examples STRING Question, Answer LET Question = "What is your street address ..." GOSUB ask LET Question = "What is your city, state and zip ..." GOSUB ask END :ask ' Sub to ask a question, get an answer, and log them to a file LET Answer = "" PRINTLN "@X0E",Question INPUT "",Answer NEWLINES 2 FPUTLN 0,"Q: ",STRIPATX(Question) FPUTLN 0,"A: ",Answer RETURN See Also GOTO Statement, RETURN Statement GOTO Statement Function Transfer program control. Syntax GOTO label label The label to which control should be transferred. Remarks GOTO is an essential part of just about every programming language, and it is also an overused part of every one of those languages. When you need to make a decision and alter program flow based on some condition it is a necessary evil. For example, it is very useful in getting out of deeply nested loops when a critical error of some sort occurs. For the most part, avoid it if at all possible. Look for other options to write your program, such as block IF, WHILE, and FOR statements. They are much easier to understand and maintain than code with GOTO statements sprinkled liberally throughout. Examples INTEGER i STRING s FOPEN 1,"FILE.DAT",O_RD,S_DW WHILE (UPPER(s) <> "QUIT") DO FGET 1,s IF (FERR(1)) THEN PRINTLN "Error, aborting..." GOTO exit ENDIF INC i PRINTLN "Line ",i,": ",s ENDWHILE :exit FCLOSE 1 See Also GOSUB Statement, RETURN Statement GRAFMODE() Function Function Report the graphics mode in use. Syntax GRAFMODE() No arguments are required Return Type and Value STRING Returns a letter indicating the current graphics supported. Remarks This function will return one of four possible responses. "N" will be returned if no graphics support is currently available. "A" will be returned for non-graphics users that do have ANSI support available for positioning. "G" will be returned for users who support full ANSI graphics. Finally, "R" will be returned for users who support RIPscrip. Examples IF (GRAFMODE() = "R") THEN PRINT "RIPscrip" ELSE IF (GRAFMODE() = "G") THEN PRINT "Full ANSI" ELSE IF (GRAFMODE() = "A") THEN PRINT "ANSI positioning" ELSE IF (GRAFMODE() = "N") THEN PRINT "No" ELSE PRINT "Unknown" ENDIF PRINTLN " Graphics Supported" See Also ANSIPOS Statement, ANSION() Function, BACKUP Statement, FORWARD Statement, GETX() Function, GETY() Function GRAPH Constant Function Set the graphics specific file search flag in a DISPFILE statement. Value 1 = 1b = 1o = 1h Remarks The DISPFILE statement will allow you to display a file to the user, and optionally to have PCBoard look for alternate security, graphics, and/or language specific files. This flag instructs PCBoard to search for alternate graphics files (ANSI or RIPscrip) via the G and R suffix. The current graphics mode may be obtained with the GRAFMODE() function. Examples STRING s DISPFILE "MNUA",SEC+GRAPH+LANG INPUT "Option",s See Also DISPFILE Statement, GRAFMODE() Function, LANG Constant, SEC Constant GUIDE Constant Function Set the display input guide flag in an INPUTSTR or PROMPTSTR statement. Value 4 = 100b = 4o = 4h Remarks The INPUTSTR and PROMPTSTR statements have the ability to display the length of an input field, regardless of ANSI availability, if you use this constant with the FIELDLEN constant. If ANSI is not available and this constant is used, the user will see the input field width marked using "(---)" above the input field. Examples STRING pwd INPUTSTR "Enter id number",pwd,@X0E,4,"0123456789",FIELDLEN+GUIDE IF (pwd <> "1234") PRINTLN "Bad id number" See Also FIELDLEN Constant, INPUTSTR Statement, PROMPTSTR Statement HANGUP Statement Function Hangup on the user and perform abnormal logoff processing. Syntax HANGUP No arguments are required Remarks This statement is useful in situations where you need to get the caller off immediately without any delay or notice. It will hangup on the caller, do all logoff processing, and log an abnormal logoff to the callers log. Examples STRING s INPUT "What do you want to do",s IF (s = "G") THEN GOODBYE ELSEIF (s = "BYE") THEN BYE ELSEIF (s = "HANG") THEN HANGUP ELSE KBDSTUFF s ENDIF See Also BYE Statement, GOODBYE Statement HELPPATH() Function Function Return the path of help files as defined in PCBSetup. Syntax HELPPATH() No arguments are required Return Type & Value STRING Returns the path of the PCBoard help files. Remarks This function will return the path where help files are located as defined in PCBSetup. This can be useful when you want to add system help capabilities to your PPE application. Examples PRINTLN "HELP FOR THE R (READ) COMMAND:" PRINTLN "------------------------------" NEWLINE DISPFILE HELPPATH()+"HLPR",GRAPH+LANG+SEC See Also HIGHASCII Constant Function Set the allow high ASCII flag in an INPUTSTR or PROMPTSTR statement. Value 4096 = 1000000000000b = 10000o = 1000h Remarks The INPUTSTR and PROMPTSTR statements have the ability to allow high ASCII characters to be input regardless of the valid character string specified, but only if the SysOp has disabled the high ASCII filter in PCBSetup. Examples STRING pwd INPUTSTR "Enter password",pwd,@X0E,4,MASK_ASCII(),HIGHASCII GETUSER IF (pwd <> U_PWD) HANGUP See Also INPUTSTR Statement, PROMPTSTR Statement HOUR() Function Function Extract the hour from a specified time of day. Syntax HOUR(texp) texp Any time expression. Return Type & Value INTEGER Returns the hour from the specified time expression (texp). Valid return values are from 0 to 23. Remarks This function allows you to extract a particular piece of information about a TIME value, in this case the hour of the time of day expression. Examples PRINTLN "The hour is ",HOUR(TIME()) See Also MIN() Function, SEC() Function I2S() Function Function Convert an integer to a string in a specified number base. Syntax I2S(int,base) int Any integer expression to convert to string format. base An integer expression with the number base (2 through 36) to convert to. Return Type & Value STRING Returns the int converted to a string in the specified number base. Remarks People work with decimal (base 10) numbers, whereas computers work with binary (base 2) numbers. It is often more convienient to display numbers in a format other than decimal for clarity, compactness, or other reasons. This function will convert a number to string format in any number base from 2 to 36. So, I2S(10,2) would return a string of "1010"; I2S(35,36) would return "Z". For more information on number bases, consult . Examples INTEGER i,num INPUTINT "Enter a number (decimal)",num,@X0E FOR i = 2 TO 36 PRINTLN num," base 10 = ",I2S(num,i)," base ",i NEXT See Also S2I() Function IF/ELSEIF/ELSE/ENDIF Statement Function Execute one or more statments if a condition is true. Syntax I F ( b e x p ) s t a t e m e n t - o r - I F ( b e x p ) T H E N s t a t e m e n t ( s ) [ELSEIF (bexp) THEN] ' optional in a block IF [ s t a t e m e n t ( s ) ] [ELSEIF (bexp) THEN] ' you may have multiple ELSEIF s t a t e m e n t ( s ) [ s t a t e m e n t ( s ) ] [ELSE] ' optional in a block IF [ s t a t e m e n t ( s ) ] ENDIF bexp Any boolean expression. statement Any valid PPL statement. Remarks The IF statement supports two types of structures: logical and block. A logical IF statement is a single statement; if a condition is TRUE, execute a single statement. A block IF can be one or more statements with multiple conditions to test for. The start of a block IF loop is differentiated from a logical IF loop by the THEN keyword immediately after the condition. In a block IF statement the first condition to evaluate to TRUE will be executed, after which control will be transferred to the statement following the ENDIF. If none of the conditions are TRUE by the time an ELSE statement is reached then the statements between the ELSE and ENDIF will be processed. If none of the conditions are TRUE and an ELSE statement is never found then none of the conditions will be executed; instead, control will be transferred to the statement after the ENDIF. Examples IF (CURSEC() < 10) END ' Insufficient security, terminate execution IF (CURSEC() < 20) THEN PRINTLN "Your security is less than 20" ELSEIF (CURSEC() > 30) THEN PRINTLN "Your security is greater than 30" ELSEIF (CURSEC() = 25) THEN PRINTLN "Your security is 25" ELSE PRINTLN "Your security is level",CURSEC() ENDIF See Also FOR/NEXT Statement, WHILE/ENDWHILE Statement INC Statement Function Increment the value of a variable. Syntax INC var var The variable with the value to increment Remarks Many programs require extensive addition and subtraction, and most often, a value is increased or decreased by 1. This statement allows for a shorter, more efficient method of increasing (incrementing) a value by 1 than adding 1 to a variable and assigning the result to the same variable. Examples INTEGER i PRINTLN "Countdown:" LET i = 0 WHILE (i <= 10) DO PRINTLN "T plus ",i INC i ENDWHILE See Also DEC Statement INKEY() Function Function Get the next key input. Syntax INKEY() No arguments are required Return Type and Value STRING Returns a single character for displayable characters or a string for cursor movement and function keys. Remarks This function will return a single character long string for most key presses. Additionally, it will return key names for function keys and cursor movement keys if it finds an ANSI sequence or DOORWAY mode sequence. It will return keystrokes from both the remote caller as well as the local BBS node. However, realize that many function keys are reserved by PCBoard for BBS related uses and may not be available for your applications that require SysOp input. Examples STRING key WHILE (key <> CHR(27)) DO LET key = INKEY() IF (LEFT(key,5) = "SHIFT") THEN PRINTLN "It was a shifted key" ELSEIF (LEFT(key,4) = "CTRL") THEN PRINTLN "It was a control key" ELSEIF (LEFT(key,3) = "ALT") THEN PRINTLN "It was an alternate key" ENDIF PRINTLN "The key was ",key ENDWHILE See Also KINKEY() Function, MGETBYTE() Function, MINKEY() Function INPUT Statement Function Prompt the user for a string of text. Syntax INPUT prompt,var prompt A string expression with the prompt to display to the user. var The variable in which to store the user's input. Remarks This statement will accept any string of input from the user, up to 60 characters maximum length. In addition to displaying the prompt, it will display parenthesis around the input field if the user is in ANSI mode. Because of this, you should generally limit your prompts to 15 characters or less. Examples BOOLEAN b DATE d INTEGER i MONEY m STRING s TIME t INPUT "Enter BOOLEAN",b INPUT "Enter DATE",d INPUT "Enter INTEGER",i INPUT "Enter MONEY",m INPUT "Enter STRING",s INPUT "Enter TIME",t PRINTLN b," ",d," ",i PRINTLN m," ",s," ",t See Also INPUT... Statement, INPUTSTR Statement, INPUTTEXT Statement, PROMPTSTR Statement INPUT... Statements Function Prompt the user for a string of text of a specific length and with type dependent valid characters. Syntax INPUT... prompt,var,color prompt A string expression with the prompt to display to the user. var The variable in which to store the user's input. color An integer expression with the color to display the prompt in. INPUT should be followed by one of the following types (without spaces between the INPUT and type): CC, DATE, INT, MONEY, TIME, or YN. Remarks This statement will accept a string of input from the user, with a set of valid characters and up to a maximum length (MAXLEN) determined by the statement in use. In addition to displaying the prompt, it will display parenthesis around the input field if the user is in ANSI mode. Because of this, you should generally limit your prompts to a length determined by the following formula: (80-MAXLEN-4). Here are the valid character masks and maximum length values for each of the input statements: INPUT CC DATE INT MONEY TIME Y N Valid "0123456 "01234567 "01234567 "012345678 "0123456 * Chars 789" 89-/" 89+-" 9+-$." 789:" Max 16 8 11 13 8 1 Length * The INPUTYN statement valid characters are dependent on the users language selection. Usually they will be "YN" for english language systems. Other letters may be defined for different languages in PCBML.DAT. Examples DATE d INTEGER i MONEY m STRING cc, yn TIME t INPUTCC "Enter Credit Card Number",cc INPUTDATE "Enter DATE",d INPUTINT "Enter INTEGER",i INPUTMONEY "Enter MONEY",m INPUTTIME "Enter TIME",t INPUTYN "Enter Yes/No Response",s PRINTLN cc," ",d," ",i PRINTLN m," ",t," ",yn See Also INPUT Statement, INPUTSTR Statement, INPUTTEXT Statement, PROMPTSTR Statement INPUTSTR Statement Function Prompt the user for a string of text in a specific format. Syntax INPUTSTR prompt,var,color,len,valid,flags prompt A string expression with the prompt to display to the user. var The variable in which to store the user's input. color An integer expression with the color to display the prompt in. len An integer expression with maximum length of text to input. valid A string expression with the valid characters that the user may enter. flags An integer expression with flags to modify how the statement works. Remarks This statement will accept a string of input from the user, up to the length defined. The prompt parameter will be displayed to the user in the specified color before accepting input. Only characters found in the valid parameter will be accepted. However, the flags parameter may affect how prompt is displayed and the valid characters that are accepted. Individual flags may be added together as needed. Several functions exist to easily specify commonly used valid character masks. They are MASK_ALNUM(), MASK_ALPHA(), MASK_ASCII(), MASK_FILE(), MASK_NUM(), MASK_PATH(), and MASK_PWD(). Defined flag values are AUTO, DEFS, ECHODOTS, ERASELINE, FIELDLEN, GUIDE, HIGHASCII, LFAFTER, LFBEFORE, NEWLINE, NOCLEAR, STACKED, UPCASE, WORDWRAP, and YESNO. Examples BOOLEAN b DATE d INTEGER i MONEY m STRING s TIME t INPUTSTR "Enter BOOLEAN",b,@X0E,1,"10",LFBEFORE+NEWLINE INPUTSTR "Enter DATE",d,@X0F,8,"0123456789- ",NEWLINE+NOCLEAR INPUTSTR "Enter INTEGER",i,@X07,20,MASK_NUM(),NEWLINE INPUTSTR "Enter MONEY",m,@X08,9,MASK_NUM()+".",NEWLINE+DEFS+FIELDLE N INPUTSTR "Enter STRING",s,@X09,63,MASK_ASCII(),NEWLINE+FIELDLEN+GUI DE INPUTSTR "Enter TIME",t,@X0A,5,"0123456789"+":",NEWLINE+LFAFTER PRINTLN b," ",d," ",i PRINTLN m," ",s," ",t See Also INPUT Statement, INPUT... Statement, INPUTTEXT Statement, PROMPTSTR Statement INPUTTEXT Statement Function Prompt the user in a specified color for a string of text of specified length. Syntax INPUTTEXT prompt,var,color,len prompt A string expression with the prompt to display to the user. var The variable in which to store the user's input. color An integer expression with the color to display the prompt in. len An integer expression with maximum length of text to input. Remarks This statement will accept any string of input from the user, up to the length defined. In addition to displaying the prompt, it will display parenthesis around the input field if the user is in ANSI mode. Because of this, you should generally limit your prompts to (80-len-4) characters or less. Examples BOOLEAN b DATE d INTEGER i MONEY m STRING s TIME t INPUTTEXT "Enter BOOLEAN",b,@X0E,1 INPUTTEXT "Enter DATE",d,@X0F,8 INPUTTEXT "Enter INTEGER",i,@X07,20 INPUTTEXT "Enter MONEY",m,@X08,9 INPUTTEXT "Enter STRING",s,@X09,63 INPUTTEXT "Enter TIME",t,@X0A,5 PRINTLN b," ",d," ",i PRINTLN m," ",s," ",t See Also INPUT Statement, INPUT... Statement, INPUTSTR Statement, PROMPTSTR Statement INSTR() Function Function Find the position of one string within another string. Syntax INSTR(str,sub) str A string expression to look for sub in. sub A string expression to search for. Return Type & Value INTEGER Returns the 1-based position of sub within str or 0 if sub is not found within str. Remarks This function is useful for determining if a particular word or phrase exists in a string. The return value is the position of the sub string within the longer string. The first character of str is position 1, the second is position 2, and so on. If sub is not found in str, 0 is returned. Examples STRING s WHILE (INSTR(UPPER(s),"QUIT") = 0) DO INPUTTEXT "Enter string",s,@X0E,40 NEWLINE PRINTLN s ENDWHILE See Also INTEGER Type Function Declare one or more variables of type integer. Syntax INTEGER var|arr(s[,s[,s]])[,var|arr(s[,s[,s]])] var The name of a variable to declare. Must start with a letter [A-Z] which may be followed by letters, digits [0-9] or the underscore [_]. May be of any length but only the first 32 characters are used. arr The name of an array variable to declare. The same naming conventions as var are used. s The size (0-based) of an array variable dimension. Any constant integer expression is allowed. Remarks INTEGER variables are stored as four byte signed long integers. The range of an INTEGER is -2,147,483,648 - +2,147,483,647. An INTEGER assignment to a STRING will result in a string with the representation of the number (similar to BASIC's STR$ function and C's ltoa function). A STRING to INTEGER assignment will convert the string back to the four byte binary integer value (similar to BASIC's VAL function and C's atol function). If an INTEGER is assigned to or from any other type, an appropriate conversion is performed automatically by PPL. Examples INTEGER i, year, cardDeck(4*13), matrix(2,2), matrices(3,4,5) See Also BOOLEAN Type, DATE Type, MONEY Type, STRING Type, TIME Type JOIN Statement Function Execute the join conference command with desired sub-commands. Syntax JOIN cmds cmds A string expression with any desired sub-commands for the join conference command. Remarks This statement will allow you to access the join conference (the J command from the main menu), and any join conference sub- commands, under PPE control. Note that this statement will destroy any previously tokenized string expression. If you have string tokens pending at the time of the DIR statment you should save them first and then retokenize after the DIR statement is complete. Examples STRING yn INPUTYN "Join SysOp conference",yn,@X0E IF (yn = YESCHAR()) JOIN 4 See Also KBDCHKOFF Statement Function Turn off keyboard timeout checking. Syntax KBDCHKOFF No arguments are required Remarks PCBoard has built in automatic keyboard timeout detecting. What this means is that if someone should remain online for a SysOp defined period of time without typing anything for PCBoard to process, PCBoard will detect it, log it to the callers log, and recycle back to the call waiting screen. Some applications require the ability to turn this off; for example, a process that will take a while without interacting with the caller should turn off keyboard timeout testing to keep PCBoard from thinking that the user has stopped entering information. Normally, PCBoard would just recycle at that point. So, just before you start a section of code that should continue for a while without user input, you should issue a KBDCHKOFF statement. It will turn off the automatic keyboard timeout checking. When you've finished the block where keyboard timeout checking has been disabled, issue the KBDCHKON statement to turn it back on. Examples KBDCHKOFF WHILE (RANDOM(10000) <> 0) PRINT "." ' Something to take a long time! KBDCHKON See Also KBDCHKON Statement KBDCHKON Statement Function Turn on keyboard timeout checking. Syntax KBDCHKON No arguments are required Remarks PCBoard has built in automatic keyboard timeout detecting. What this means is that if someone should remain online for a SysOp defined period of time without typing anything for PCBoard to process, PCBoard will detect it, log it to the callers log, and recycle back to the call waiting screen. Some applications require the ability to turn this off; for example, a process that will take a while without interacting with the caller should turn off keyboard timeout testing to keep PCBoard from thinking that the user has stopped entering information. Normally, PCBoard would just recycle at that point. So, just before you start a section of code that should continue for a while without user input, you should issue a KBDCHKOFF statement. It will turn off the automatic keyboard timeout checking. When you've finished the block where keyboard timeout checking has been disabled, issue the KBDCHKON statement to turn it back on. Examples KBDCHKOFF WHILE (RANDOM(10000) <> 0) PRINT "." ' Something to take a long time! KBDCHKON See Also KBDCHKOFF Statement KBDFILE Statement Function Stuff the contents of a text file into the keyboard buffer for later processing. Syntax KBDFILE file file A string expression with the filename whose contents should be stuffed into the keyboard buffer. Remarks This statement allows you to feed a series of keystrokes to PCBoard as though they were typed in by the user. This is useful when you need to feed a series of commands to PCBoard one right after another and they would add up to more than 256 characters (the maximum buffer size for the KBDSTUFF statement). Examples INTEGER retcode SHOWOFF OPENCAP "NEWFILES.LST",retcode KBDSTUFF CHR(13) DIR "N;S;A;NS" CLOSECAP SHOWON SHELL TRUE,retcode,"PKZIP","-mex NEWFILES NEWFILES.LST" KBDFILE "FLAGFILE.CMD" See Also KBDSTUFF Statement KBDSTUFF Statement Function Stuff a string into the keyboard buffer for later processing. Syntax KBDSTUFF str str A string expression to stuff into the keyboard buffer for later processing. Remarks This statement allows you to feed a series of keystrokes to PCBoard as though they were typed in by the user. This can be especially useful when you are replacing an existing command; add your PPE file to the CMD.LST file so that it takes the place of the built in command, then have your PPE stuff the original (or modified command) back to the keyboard buffer. PCBoard will then process it as soon as you exit your PPE application. It can also be used when building new commands that should perform several built in operations automatically. A maximum of 256 characters at a time can be stuffed into the keyboard buffer. If you need more than this, you should use the KBDFILE statement. Examples INTEGER retcode SHOWOFF OPENCAP "NEWFILES.LST",retcode KBDSTUFF CHR(13) DIR "N;S;A;NS" CLOSECAP SHOWON SHELL TRUE,retcode,"PKZIP","-mex NEWFILES NEWFILES.LST" KBDSTUFF "FLAG NEWFILES.ZIP" See Also KBDFILE Statement KINKEY() Function Function Get the next key input from the local keyboard only. Syntax KINKEY() No arguments are required Return Type and Value STRING Returns a single character for displayable characters or a string for cursor movement and function keys. Remarks This function will return a single character long string for most key presses. Additionally, it will return key names for function keys and cursor movement keys. It will only return keystrokes from the local BBS node's keyboard. However, realize that many function keys are reserved by PCBoard for BBS related uses and may not be available for your applications that require SysOp input. Examples STRING key WHILE (key <> CHR(27)) DO LET key = KINKEY() IF (LEFT(key,5) = "SHIFT") THEN PRINTLN "It was a shifted key" ELSEIF (LEFT(key,4) = "CTRL") THEN PRINTLN "It was a control key" ELSEIF (LEFT(key,3) = "ALT") THEN PRINTLN "It was an alternate key" ENDIF PRINTLN "The key was ",key ENDWHILE See Also INKEY() Function, MGETBYTE() Function, MINKEY() Function LANG Constant Function Set the language specific file search flag in a DISPFILE statement. Value 4 = 100b = 4o = 4h Remarks The DISPFILE statement will allow you to display a file to the user, and optionally to have PCBoard look for alternate security, graphics, and/or language specific files. This flag instructs PCBoard to search for alternate language files via the language extension. The current language extension may be obtained with the LANGEXT() function. Examples STRING s DISPFILE "MNUA",SEC+GRAPH+LANG INPUT "Option",s See Also DISPFILE Statement, GRAPH Constant, LANGEXT() Function, SEC Constant LANGEXT() Function Function Get the file extension for the current language. Syntax LANGEXT() No arguments are required Return Type and Value STRING Returns a ".XXX" formatted string where XXX is the extension text (could be 1, 2 or 3 characters long depending on the configuration and language in use). Remarks This function allows you to access the file extension used by SysOp definable and system language specific files. You may use it to create your own filenames that are language specific. Examples PRINTLN "Brief user profile" NEWLINE PRINTLN " Security: ",CURSEC() PRINTLN "Graphics Mode: ",GRAFMODE() PRINTLN " Language: ",LANGEXT() See Also LEFT() Function Function Access the left most characters from a string. Syntax LEFT(str,chars) str A string expression to take the left most characters of. chars An integer expression with the number of characters to take from the left end of str. Return Type & Value STRING Returns a string with the left most chars characters of str. Remarks This function will return a sub string with the left most chars characters of a specified string. This can be useful in data processing as well as text formatting. If chars is less than or equal to 0 then the returned string will be empty. If chars is greater than the length of str then the returned string will have spaces added to the left to pad it out to the full length specified. Examples WHILE (RANDOM(250) <> 0) PRINT LEFT(RANDOM(250),4)," " STRING s FOPEN 1,"DATA.TXT",O_RD,S_DN WHILE (!FERR(1)) DO FGET 1,s PRINT RTRIM(LEFT(s,25)," ")," - " PRINTLN RIGHT(s,LEN(s)-25) ENDWHILE FCLOSE 1 See Also MID() Function, RIGHT() Function LEN() Function Function Access the length of a string. Syntax LEN(str) str Any string expression. Return Type & Value INTEGER Returns the length of a string. Remarks This function will return the length of a string. The value returned will always be between 0 (an empty string) and 256 (the maximum length of a string). Examples STRING s FOPEN 1,"DATA.TXT",O_RD,S_DN WHILE (!FERR(1)) DO FGET 1,s PRINTLN "The length of the current string is ",LEN(s) ENDWHILE FCLOSE 1 See Also LET Statement Function Evaluate an expression and assign the result to a variable. Syntax L E T v a r = e x p r - o r - var = expr var Variable to which the result of expr should be assigned. expr Any valid PPL expression. Remarks The LET statement supports modes of operation: explicit and implicit. An explicit LET statement always includes all of the parts in the first example above (the LET keyword, the variable, the equal sign, and the expression). An implicit LET statement does not need the LET keyword; the format (var = expr) is sufficient. However, the implicit form will not always work. For example, if you had a variable named PRINT (which is also a statement name) you could not use PRINT = expr; PPL expects the first word on a line to be a statement name, and if it isn't, it is an implicit LET statement. Since PPL would find the PRINT statement first it would try to process the rest of the line as a PRINT statement. This is easily avoided by using the LET keyword and making it an explicit LET statement (LET PRINT = expr). Examples INTEGER i STRING s GETUSER LET U_PWD = "NEWPWD" LET s = "This is a string" LET i = 7*9+9*7 PUTUSER See Also LFAFTER Constant Function Set the extra line feed after prompt flag in a DISPTEXT, INPUTSTR, or PROMPTSTR statement. Value 256 = 100000000b = 400o = 100h Remarks The INPUTSTR, PROMPTSTR, and DISPTEXT statements have the ability to send an extra carriage return/line feed after a prompt is displayed automatically and without the need to make a separate call to the NEWLINE statement. Examples STRING pwd INPUTSTR "Enter id",pwd,@X0E,4,"0123456789",LFBEFORE+NEWLINE+LFAFTE R IF (pwd <> "1234") PRINTLN "Bad id number" See Also DISPTEXT Statement, INPUTSTR Statement, LFBEFORE Constant, NEWLINE Constant, PROMPTSTR Statement LFBEFORE Constant Function Set the line feed before prompt flag in a DISPTEXT, INPUTSTR, or PROMPTSTR statement. Value 128 = 10000000b = 200o = 80h Remarks The INPUTSTR, PROMPTSTR, and DISPTEXT statements have the ability to send a carriage return/line feed before a prompt is displayed automatically and without the need to make a separate call to the NEWLINE statement. Examples STRING pwd INPUTSTR "Enter id",pwd,@X0E,4,"0123456789",LFBEFORE+NEWLINE+LFAFTE R IF (pwd <> "1234") PRINTLN "Bad id" See Also DISPTEXT Statement, INPUTSTR Statement, LFAFTER Constant, NEWLINE Constant, PROMPTSTR Statement LOG Statement Function Log a message to the callers log. Syntax LOG msg,left msg A string expression to write to the callers log. left A boolean expression with value TRUE if msg should be left justified, FALSE if msg should be indented six spaces. Remarks There are two primary uses for this statement. First and foremost, it allows you to keep the SysOp informed of what the user does while using your PPL application. Secondly, it can allow you to track information within your PPE while debugging. Examples BOOLEAN flag PRINT "Type QUIT to exit..." WAITFOR "QUIT",flag,60 IF (!flag) LOG "User did not type QUIT",FALSE LOG "***EXITING PPE***",TRUE See Also LOGGEDON() Function Function Determine if a user has completely logged on to the BBS. Syntax LOGGEDON() No arguments are required Return Type and Value BOOLEAN Returns TRUE if the user has completed logging in, FALSE otherwise. Remarks There are some features of PPL that are not available until the user has completely logged in, such as the user variables and functions and the CALLNUM() function. This function will allow you to detect whether or not a user has completely logged in and if selected PPL features are available. Examples IF (!LOGGEDON()) LOG "USER NOT LOGGED ON",0 See Also LOGIT Constant Function Set the write prompt to callers log flag in a DISPTEXT statement. Value 32768 = 1000000000000000b = 100000o = 8000h Remarks The DISPTEXT statement has the ability to write a specified prompt to the callers log automatically without the need to use the LOG statement. This flag will indent the prompt six spaces in the callers log. Examples DISPTEXT 4,LFBEFORE+LFAFTER+BELL+LOGIT See Also DISPTEXT Statement, LOGITLEFT Constant LOGITLEFT Constant Function Set the write prompt to callers log left justified flag in a DISPTEXT statement. Value 65536 = 10000000000000000b = 200000o = 10000h Remarks The DISPTEXT statement has the ability to write a specified prompt to the callers log automatically without the need to use the LOG statement. This flag will not indent the prompt in the callers log. Examples DISPTEXT 4,LFBEFORE+LFAFTER+BELL+LOGITLEFT See Also DISPTEXT Statement, LOGIT Constant LOWER() Function Function Converts uppercase characters in a string to lowercase. Syntax LOWER(sexp) sexp Any string expression. Return Type & Value STRING Returns sexp with all uppercase characters converted to lowercase. Remarks Although "STRING" is technically different from "string" (ie, the computer doesn't recognize them as being the same because one is uppercase and the other is lowercase), it is often necessary to save, display or compare information in a case insensitive format. This function will return a string with all uppercase characters converted to lowercase. So, using the above example, LOWER("STRING") would return "string". Examples STRING s WHILE (UPPER(s) <> "QUIT") DO INPUT "Text",s PRINTLN LOWER(s) ENDWHILE See Also UPPER() Function LTRIM() Function Function Trim a specified character from the left end of a string. Syntax LTRIM(str,ch) str Any string expression. ch A string with the character to strip from the left end of str. Return Type & Value STRING Returns the trimmed str. Remarks A common need in programming is to strip leading and/or trailing spaces (or other characters). This function will strip a specified character from the left end of a string and return the trimmed string. Examples STRING s LET s = " TEST " PRINTLN LTRIM(s," ") ' Will print "TEST " PRINTLN LTRIM(".....DA"+"TA.....",".") ' Will print "DATA....." PRINTLN LTRIM(".....DA"+"TA....."," ") ' Will print ".....DATA....." See Also RTRIM() Function, TRIM() Function MASK_...() Functions Function Return a string for use as a valid character mask. Syntax MASK_...() No arguments are required MASK_ should be followed by one of the following mask types: ALNUM, ALPHA, ASCII, FILE, NUM, PATH, or PWD. Return Type and Value STRING Returns a string with a set of characters to use as valid input for an INPUTSTR or PROMPTSTR statement. Remarks There are many situations in which you will need to use an INPUTSTR or PROMPTSTR statement to access the input field length of flags. However, all you need to use a 'standard' set of input characters. These functions provide you with some of the most common valid character masks. They are: MASK_ALNUM() which returns A-Z, a-z, and 0-9; MASK_ALPHA() which returns A-Z and a-z; MASK_ASCII() which returns all characters from space (ASCII 32) to tilde (ASCII 126); MASK_FILE() which returns all legal file name characters; MASK_NUM() which returns 0-9; MASK_PATH() which returns all legal path name characters; and, finally, MASK_PWD() which returns a set of valid characters for use in passwords. Examples INTEGER i STRING s INPUTSTR "Enter a number from 0 to 1000",i,@X0E,4,MASK_NUM(),DEFS PROMPTSTR 148,s,12,MASK_PWD(),ECHODOTS INPUTSTR "Enter your comment",s,@X0E,60,MASK_ASCII(),DEFS See Also INPUTSTR Statement, PROMPTSTR Statement MAXNODE() Function Function Determine how many nodes a system may have. Syntax MAXNODE() No arguments are required Return Type and Value INTEGER Returns the node limit available to the system running the PPE file. Remarks Every package of PCBoard purchased comes with a license agreement that limits it to a maximum number of nodes. This node limit restricts various features of PCBoard, such as the WHO display and CHAT functions. This limit is available to your PPL applications via this function. Examples INTEGER i FOR i = 1 TO MAXNODE() RDUNET i IF ((UN_STAT() = "A") | (UN_STAT() = "U")) THEN BROADCAST i,i,"Hello, how are you?" IF (PCBNODE() = i) PRINLN "Quit talking to yourself" ENDIF NEXT See Also MESSAGE Statement Function Enter a message under PPL control. Syntax MESSAGE conf,to,from,sub,sec,pack,rr,echo,file conf An integer expression with the conference in which to post the message. to A string expression with the user name to which the message should be sent. from A string expression with the user name that the message should be sent from. sub A string expression with the subject of the message. sec A string expression with the desired security for the message ("N"for none or "R" for receiver only). pack A date expression with the packout date for the message (or 0 for no packout date). rr A boolean expression with the return receipt requested flag (TRUE to request a return receipt, FALSE otherwise). echo A boolean expression with the echo flag (TRUE to echo the message, FALSE otherwise). file A string expression with the path and file name of the text file to use as the message text. Remarks This statement will allow you to leave a message from any user (or any 'name' you wish to use) to any user on your system. This can be useful if you want to notify a user of information that they should download in a QWK packet or that they might miss too easily as a quick one liner on screen from the PPL. Examples IF (CURSEC() < 20) THEN MESSAGE 0,U_NAME(),"SYSOP","REGISTER","R",DATE(),TRUE,FALSE ,"REG.TXT" ENDIF See Also MGETBYTE() Function Function Get the next byte input from the modem. Syntax MGETBYTE() No arguments are required Return Type and Value INTEGER Returns the value (0-255) of the next byte from the modem input buffer or -1 if no bytes are pending. Remarks Any character may be received from the users modem. Normally PCBoard will filter and convert strings (ESC sequences and DOORWAY codes) automatically. However, sometimes this isn't desired and you need to access the incoming bytes directly. This function will look directly for incoming characters from the modem and return them as a value from 0 to 255. These numbers may be converted to characters with the CHR() function if necessary. Examples INTEGER byte WHILE (byte <> 27) DO LET byte = MGETBYTE() PRINTLN "The byte value is ",byte ENDWHILE See Also INKEY() Function, KINKEY() Function, MINKEY() Function MID() Function Function Access any sub string of a string. Syntax MID(str,pos,chars) str A string expression to take the left most characters of. pos An integer expression with the position within str to start taking the sub string from. chars An integer expression with the number of characters to take from str. Return Type & Value STRING Returns a string with the specified number of characters from the specified position of str. Remarks This function will return a sub string with the specified number of characters and from the specified position of str. This can be useful in data processing as well as text formatting. The pos parameter may be less than 1 (the beginning of the str) and greater than the length of str; if it is then spaces will be added to the beginning and/or ending as needed. If chars is less than or equal to 0 then the returned string will be empty. If chars is greater than the available length of str then the returned string will have spaces added to the end(s) to pad it out to the full length specified. Examples WHILE (RANDOM(250) <> 0) PRINT MID(RANDOM(250),0,4)," " STRING s FOPEN 1,"DATA.TXT",O_RD,S_DN WHILE (!FERR(1)) DO FGET 1,s PRINT LEFT(s,5),RTRIM(MID(s,5,20)," ")," - " PRINTLN RTRIM(MID(s,LEN(s)-25,60)," ") ENDWHILE FCLOSE 1 See Also LEFT() Function, RIGHT() Function MIN() Function Function Extract the minute of the hour from a specified time of day. Syntax MIN(texp) texp Any time expression. Return Type & Value INTEGER Returns the minute of the hour from the specified time expression (texp). Valid return values are from 0 to 59. Remarks This function allows you to extract a particular piece of information about a TIME value, in this case the minute of the hour of the time of day expression. Examples PRINTLN "The minute is ",MIN(TIME()) See Also HOUR() Function, SEC() Function MINKEY() Function Function Get the next key input from the modem only. Syntax MINKEY() No arguments are required Return Type and Value STRING Returns a single character for displayable characters or a string for cursor movement and function keys. Remarks This function will return a single character long string for most key presses. Additionally, it will return key names for function keys and cursor movement keys if it encounters ESC sequences or DOORWAY codes. It will only return keystrokes from the remote users modem. Examples STRING key WHILE (key <> CHR(27)) DO LET key = MINKEY() IF (LEFT(key,5) = "SHIFT") THEN PRINTLN "It was a shifted key" ELSEIF (LEFT(key,4) = "CTRL") THEN PRINTLN "It was a control key" ELSEIF (LEFT(key,3) = "ALT") THEN PRINTLN "It was an alternate key" ENDIF PRINTLN "The key was ",key ENDWHILE See Also INKEY() Function, KINKEY() Function, MGETBYTE() Function MINLEFT() Function Function Return the users minutes left. Syntax MINLEFT() No arguments are required Return Type and Value INTEGER Returns the number of minutes the user online has left to use. Remarks This function will allow you to access how much time the user has remaining. You could use it to disable certain features at a certain point in their session. Note that this number can be either the minutes left today or this session if the SysOp does not enforce daily time limits. Examples IF (MINLEFT() > 10) THEN KBDSTUFF "D"+CHR(13) ELSE PRINTLN "Sorry, not enough time left to download" ENDIF See Also MINON() Function MINON() Function Function Return the users minutes online. Syntax MINON() No arguments are required Return Type and Value INTEGER Returns the number of minutes the user online has used this session. Remarks This function will allow you to access how much time the user has used this session. You could use it to allow or disallow certain features before a certain point in their session. Note that this number will always be the minutes used this session regardless of whether or not the SysOp enforces daily time limits. Examples IF (MINON() >= 10) THEN KBDSTUFF "D"+CHR(13) ELSE PRINTLN "Sorry, you haven't been on long enough yet to download" ENDIF See Also MINLEFT() Function MKADDR() Function Function Create a complete address from a segment and offset. Syntax MKADDR(seg,off) seg An integer expression with the segment portion of the address. off An integer expression with the offset portion of the address. Return Type & Value INTEGER Returns an integer with the complete segment:offset based address. Remarks The POKE... statements and PEEK...() functions require full addresses to read from and write to memory. Normally you will know the segment and the offset portions of the address but they will be separate. Although not difficult to integrate together, this function automates the process. The values returned can be calculated by the following formula: seg*10000h+off. Examples PRINTLN "Ticks since midnight",PEEKDW(MKADDR(0040h,006Ch)) See Also VARADDR Statement, VAROFF Statement, VARSEG Statement MKDATE() Function Function Create a complete date from separate year, month and day values. Syntax MKDATE(year,month,day) year An integer expression with the year (1900 through 2079). month An integer expression with the month (1 through 12). day An integer expression with the day of the month (1 through 31). Return Type & Value DATE Returns a date made from the specified year, month and day values. Remarks Although PPL does it's best to automatically convert values from one type to another as needed, converting STRING values to DATE values presents a special problem because of the year portion of the date. Normally the year is only expressed in a two digit format. This limits the automatic convertion to a single 100 year period. PCBoard uses year values greater than or equal to 80 as 20th century (19XX) dates, and year values less than 80 as 21st century (20XX) dates. Since you may need to access dates prior to 1980 (when processing birthdates, for example), this function allows you to take three integers (year, month and day) and build any date necessary. Examples PRINTLN "My birthdate is ",MKDATE(1967,10,31) INTEGER y,m,d INPUTINT " Your birth year",y,@X0E INPUTINT "Your birth month",m,@X0E INPUTINT " Your birth day",d,@X0E PRINTLN "Your birthdate is ",MKDATE(y,m,d) IF (MKDATE(y,m,d) < MKDATE(1967,10,31)) THEN PRINTLN "You are older than me" ELSE IF (MKDATE(y,m,d) > MKDATE(1967,10,31)) THEN PRINTLN "I am older than you" ELSE PRINTLN "We are the same age" ENDIF See Also VARADDR Statement, VAROFF Statement, VARSEG Statement